Contenuto
Indice 🔎︎

# Servizio SFDocuments.Document

La libreria SFDocuments fornisce metodi e proprietà per agevolare la gestione e la modifica dei documenti di LibreOffice.

I metodi applicabili a tutti i tipi di documento (documenti di testo, fogli elettronici, presentazioni, ecc.) sono forniti dal servizio SFDocuments.Document. Alcuni esempi sono:

- Apertura, chiusura e salvataggio dei documenti

- Accesso a proprietà standard o personalizzate dei documenti

Le proprietà, i metodi e gli argomenti contrassegnati con (*) NON sono applicabili ai documenti di Base.

I metodi e le proprietà specifici di un determinato componente di LibreOffice sono memorizzati in servizi separati, come SFDocuments.SF_Calc e SFDocuments.SF_Base.

Anche se il linguaggio Basic non offre l'ereditarietà tra le classi di oggetti, gli ultimi servizi possono essere considerati come sottoclassi del servizio SFDocuments.Document. Queste sottoclassi possono invocare le proprietà e i metodi descritti di seguito.

## Invocare il servizio

Di seguito sono riportate tre varianti del modo in cui è possibile invocare il servizio Document.

##### In Basic

Usando il metodo getDocument dal servizio ScriptForge.UI:

        Dim ui As Object, oDoc As Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.GetDocument("Untitled 1")

In alternativa potete usare i metodi CreateDocument e OpenDocument dal servizio UI.

        Set oDocA = ui.CreateDocument("Calc")
        Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")

Direttamente se il documento è già aperto.

        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow

Da una macro attivata da un evento del documento.

        Sub RunEvent(ByRef poEvent As Object)
            Dim oDoc As Object
            Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)
            ' (...)
        End Sub

Il servizio Document è strettamente collegato ai servizi UI e FileSystem.

Eccetto quando il documento è stato chiuso da un programma usando il metodo CloseDocument (che lo rende superfluo), si consiglia di liberare le risorse dopo l'uso:

        Set oDoc = oDoc.Dispose()

##### In Python

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")
        doc = ui.GetDocument("Untitled 1")
        # (...)
        doc.Dispose()

        docA = ui.CreateDocument("Calc")
        docB = ui.OpenDocument("C:\Documents\MyFile.odt")

        doc = CreateScriptService("SFDocuments.Document", "Untitled 1")

        def RunEvent(event)
            doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
            # (...)

L'uso del prefisso "SFDocuments." nella chiamata al servizio è opzionale.

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
CustomProperties (*) | No | Dictionary service | Restituisce un'istanza dell'oggetto ScriptForge.Dictionary. Dopo il suo aggiornamento, può essere passata nuovamente alla proprietà affinché aggiorni in documento. I singoli elementi del dizionario possono essere stringhe, numeri, date (di Basic) o elementi com.sun.star.util.Duration.
Description (*) | No | String | Fornisce accesso alla proprietà "Description" del documento (chiamata anche "Comments")
DocumentProperties (*) | Sì | Dictionary service | Restituisce un oggetto ScriptForge.Dictionary contenente tutte le voci. Sono comprese le statistiche del documento. Si noti che queste sono specifiche del tipo di documento. Per esempio, un documento di Calc comprende una voce "CellCount". Altri documenti no.
DocumentType | Sì | String | Un valore in formato stringa con il tipo di documento ("Base", "Calc", "Writer", ecc.)
IsBase IsCalc IsDraw IsImpress IsMath IsWriter | Sì | Boolean | Solamente una di queste proprietà è True per un determinato documento.
Keywords (*) | No | String | Fornisce l'accesso alla proprietà Keywords del documento. Rappresentata come un elenco di parole chiave separate da virgola
Readonly (*) | Sì | Boolean | True se il documento è effettivamente in modalità sola lettura
Subject (*) | No | String | Fornisce accesso alla proprietà Subject del documento.
Title (*) | No | String | Fornisce accesso alla proprietà Title del documento.
XComponent | Sì | Oggetto UNO | L'oggetto UNO com.sun.star.lang.XComponent o com.sun.star.comp.dba.ODatabaseDocument che rappresenta il documento

### Esempio:

##### In Basic

L'esempio sottostante stampa tutte le proprietà di un documento. Si noti che l'oggetto oDoc restituito dal metodo UI.OpenDocument è un oggetto SFDocuments.Document.

        Dim ui as Variant : Set ui = CreateScriptService("UI")
        Dim oDoc as Object
        Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")
        Dim propDict as Object
        Set propDict = oDoc.DocumentProperties
        Dim keys as Variant : propKeys = propDict.Keys
        Dim k as String, strProp as String
        For Each k In propKeys
            strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)
        Next k
        MsgBox strProp
        oDoc.CloseDocument()

##### In Python

Per accedere alle proprietà del documento in uno script in Python l'utente deve accedervi direttamente usando i loro nomi, come mostrato di seguito:

        doc = ui.GetDocument(r"C:\Documents\MyFile.ods")
        msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords
        bas = CreateScriptService("Basic")
        bas.MsgBox(msg)
        doc.CloseDocument()

Elenco dei metodi del servizio Document
Activate CloseDocument ExportAsPDF | PrintOut RunCommand Save | SaveAs SaveCopyAs SetPrinter

## Activate

Restituisce True se il documento può essere attivato. Altrimenti, non c'è alcuna modifica all'interfaccia utente. È equivalente al metodo Activate del servizio UI.

Questo metodo è utile quando si rende necessario portare in primo piano un documento ridotto a icona o nascosto.

### Sintassi:

svc.Activate(): bool

### Esempio:

L'esempio sottostante considera il file "My_File.ods" già aperto ma non attivo.

##### In Basic

        Dim oDoc As Object
        Set oDoc = CreateScriptService("Document", "MyFile.ods")
        oDoc.Activate()

##### In Python

        doc = CreateScriptService("Document", "MyFile.ods")
        doc.Activate()

Tenete presente che potete invocare il servizio Document passando a CreateScriptService sia "Document" sia "SFDocuments.Document"

## CloseDocument

Chiude il documento. Se il documento è già chiuso, indipendentemente da come è stato chiuso, questo metodo non ha effetto e restituisce False.

Il metodo restituirà False anche se l'utente non accetta la sua chiusura.

Restituisce True se il documento è stato chiuso correttamente.

### Sintassi:

svc.CloseDocument(saveask: bool = True): bool

### Parametri:

saveask: se è True (predefinito), l'utente viene invitato a confermare se le modifiche devono essere salvate su disco. Questo argomento viene ignorato se il documento non è stato modificato.

### Esempio:

##### In Basic

        If oDoc.CloseDocument(True) Then
            ' ...
        End If

##### In Python

        if doc.CloseDocument(True):
            # ...

## ExportAsPDF

Exports the document directly as a PDF file to the specified location. Returns True if the PDF file was successfully created.

The export options can be set either manually using the File - Export As - Export as PDF dialog or by calling the methods GetPDFExportOptions and SetPDFExportOptions from the Session service.

### Sintassi:

svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool

### Parametri:

filename: The full path and file name of the PDF to be created. It must follow the SF_FileSystem.FileNaming notation.

overwrite: Specifies if the destination file can be overwritten (Default = False). An error will occur if overwrite is set to False and the destination file already exists.

pages: String specifying which pages will be exported. This argument uses the same notation as in the dialog File - Export As - Export as PDF.

password: Specifies a password to open the PDF file.

watermark: Text to be used as watermark in the PDF file, which will be drawn in every page of the resulting PDF.

### Esempio:

##### In Basic

The following example exports the current document as a PDF file, defines a password and overwrites the destination file if it already exists.

        oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)

The code snippet below gets the current PDF export options and uses them to create the PDF file.

        Dim exportSettings as Object, oSession as Object
        oSession = CreateScriptService("Session")
        exportSettings = oSession.GetPDFExportOptions()
        ' Sets to True the option to export comments as PDF notes
        exportSettings.ReplaceItem("ExportNotes", True)
        oSession.SetPDFExportOptions(exportSettings)
        oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")

##### In Python

        doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf", password = "1234", overwrite = True)

        session = CreateScriptService("Session")
        exportSettings = oSession.GetPDFExportOptions()
        exportSettings.ReplaceItem("ExportNotes", True)
        session.SetPDFExportOptions(exportSettings)
        doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf")

## PrintOut

This method sends the contents of the document to the default printer or to the printer defined by the SetPrinter method.

Returns True if the document was successfully printed.

### Sintassi:

svc.PrintOut(pages: str = "", copies: num = 1): bool

### Parametri:

pages: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.

copies: The number of copies. Default is 1.

### Esempio:

##### In Basic

        If oDoc.PrintOut("1-4;10;15-18", Copies := 2) Then
            ' ...
        End If

##### In Python

        if doc.PrintOut(copies=3, pages='45-88'):
            # ...

## RunCommand

Esegue un comando su un documento. Il comando è eseguito senza argomenti.

Alcuni tipici comandi sono: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste, ecc.

Per eseguire comandi, il documento non deve necessariamente essere attivo.

### Sintassi:

svc.RunCommand(command: str)

### Parametri:

command: stringa con distinzione tra lettere minuscole e maiuscole contenente il comando in lingua inglese. Non viene verificata la correttezza del comando. Se non succede nulla dopo la sua chiamata, probabilmente il comando è sbagliato.

### Esempio:

L'esempio seguente esegue il comando "SelectData" in un foglio di Calc chiamato "MyFile.ods", da ciò risulterà la selezione dell'area di dati in base alla cella attualmente selezionata.

##### In Basic

        Set oDoc = CreateScriptService("Document", "MyFile.ods")
        oDoc.RunCommand("SelectData")

##### In Python

        doc = CreateScriptService("Document", "MyFile.ods")
        doc.RunCommand("SelectData")

The example above actually runs the UNO command .uno:SelectData. Hence, to use the RunCommand method it is necessary to remove the ".uno:" substring.

Ogni componente di LibreOffice dispone di un proprio insieme di comandi. Un modo semplice per imparare i comandi è quello di accedere a Strumenti > Personalizza > Tastiera. Quando posizionate il cursore del mouse sopra una funzione nell'elenco Funzione comparirà un suggerimento con il comando UNO corrispondente.

## Save

Memorizza il documento nella posizione del file da cui è stato caricato. Il metodo viene ignorato se il documento non è stato modificato.

Restituisce False se il documento non può essere salvato. Viene generato un errore se il file è aperto in sola lettura o se il nuovo file non è stato ancora salvato.

Per eseguire questo metodo non è necessario che il documento in questione sia attivo.

### Sintassi:

svc.Save(): bool

### Esempio:

##### In Basic

        If Not oDoc.Save() Then
            ' ...
        End If

##### In Python

        if not doc.Save():
            # ...

## SaveAs

Memorizza il documento in un file nella posizione specificata. La nuova posizione diventa il nuovo nome di file sul quale verranno applicate le chiamate al metodo "Save" semplice.

Restituisce False se il documento non può essere salvato. Viene sollevato un errore se la sovrascrittura della destinazione viene rifiutata o quando per la destinazione è impostato l'attributo di sola lettura.

Il documento in questione non deve essere attivo per poter eseguire questo metodo.

### Sintassi:

svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

### Parametri:

filename: una stringa contenente il nome del file da usare. Deve rispettare la notazione SF_FileSystem.FileNaming.

overwrite: se è True, il file di destinazione può essere sovrascritto (predefinito = False).

password (*): una stringa priva di spazi con la quale proteggere il documento.

filtername (*): il nome di un filtro da usare per salvare il documento. Se questo argomento viene passato, allora il filtro deve esistere.

filteroptions (*): una stringa facoltativa delle opzioni associate al filtro.

### Esempio:

##### In Basic

        oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)

##### In Python

        doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)

## SaveCopyAs

Memorizza una copia o esporta il documento nel percorso specificato del file. Il file nella posizione corrente rimane immutato.

Restituisce False se il documento non può essere salvato. Viene sollevato un errore se la sovrascrittura della destinazione viene rifiutata o quando per la destinazione è impostato l'attributo di sola lettura.

Non è necessario che il documento in questione sia attivo per eseguire questo metodo.

### Sintassi:

svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

### Parametri:

filename: una stringa contenente il nome del file da usare. Deve rispettare la notazione SF_FileSystem.FileNaming.

overwrite: Se è True, il file di destinazione può essere sovrascritto (predefinito = False).

password (*): una stringa priva di spazi con la quale proteggere il documento.

filtername (*): Il nome di un filtro da usare per salvare il documento. Se questo argomento viene passato, allora il filtro deve esistere.

filteroptions (*): una stringa facoltativa delle opzioni associate al filtro.

### Esempio:

##### In Basic

        oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)

##### In Python

        doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)

## SetPrinter

Defines the printer options for the document.

Returns True when successful.

### Sintassi:

svc.SetPrinter(opt printer: str, opt orientation: str, paperformat: str): bool

### Parametri:

printer: The name of the printer queue where to print to. When absent, the default printer is set.

orientation: Either PORTRAIT or LANDSCAPE. When absent, left unchanged with respect to the printer settings.

paperformat: Specifies the paper format as a string value that can be either A3, A4, A5, LETTER, LEGAL or TABLOID. Left unchanged when absent.

### Esempio:

##### In Basic

        oDoc.SetPrinter(Orientation := "PORTRAIT")

##### In Python

        doc.SetPrinter(paperformat='TABLOID')

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

Argomenti correlati

Servizio ScriptForge.UI

Servizio ScriptForge.Dictionary