Inhalte
Index 🔎︎

# Dienst SFDocuments.Document

Die Bibliothek SFDocuments stellt Methoden und Eigenschaften bereit, um die Verwaltung und Bearbeitung von LibreOffice-Dokumenten zu erleichtern.

Der Dienst SFDocuments.Document stellt Methoden zur Verfügung, die für alle Arten von Dokumenten (Textdokumente, Blätter, Präsentationen, …) anwendbar sind. Einige Beispiele sind:

- Dokumente öffnen, schließen und speichern

- Zugriff auf standardmäßige oder benutzerdefinierte Eigenschaften von Dokumenten

Die mit (*) gekennzeichneten Eigenschaften, Methoden oder Argumente sind NICHT auf Basic-Dokumente anwendbar.

Methoden und Eigenschaften, die für bestimmte LibreOffice-Komponenten spezifisch sind, werden in separaten Diensten gespeichert, wie beispielsweise SFDocuments.SF_Calc und SFDocuments.SF_Base.

Obwohl die Basic-Sprache keine Vererbung zwischen Objektklassen anbietet, können letztere Dienste als Unterklassen des Dienstes SFDocuments.Document betrachtet werden. Solche Unterklassen können die unten beschriebenen Eigenschaften und Methoden aufrufen.

## Dienstaufruf

Nachfolgend finden Sie drei Varianten, wie der Dienst Document aufgerufen werden kann.

##### In Basic

Verwenden der Methode getDocument des Dienstes ScriptForge.UI:

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

Alternativ können Sie die Methoden CreateDocument und OpenDocument des Dienstes UI verwenden.

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

Direkt, wenn das Dokument bereits geöffnet ist.

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

Mit einem Makro, das durch ein Dokumentereignis ausgelöst wird.

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

Der Dienst Document ist eng mit den Diensten UI und FileSystem verwandt.

Außer wenn das Dokument per Programm mit der Methode "CloseDocument" geschlossen wurde (sie ist dann überflüssig), empfiehlt es sich, Ressourcen nach der Verwendung freizugeben:

        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)
            # (...)

Die Verwendung des Präfixes "SFDocuments." beim Aufruf des Dienstes ist optional.

## Eigenschaften

Name | Schreibgeschützt | Typ | Beschreibung
CustomProperties (*) | Nein | Dictionary service | Gibt eine Objektinstanz ScriptForge.Dictionary zurück. Kann nach der Aktualisierung erneut an die Eigenschaft übergeben werden, um das Dokument zu aktualisieren. Einzelne Elemente des Wörterbuchs können entweder Zeichenfolgen, Zahlen, (Basic-)Datumsangaben oder Elemente vom Typ com.sun.star.util.Duration sein.
Description (*) | Nein | String | Ermöglicht den Zugriff auf die Beschreibungseigenschaft des Dokuments (auch bekannt als "Kommentare").
DocumentProperties (*) | Ja | Dictionary service | Gibt ein Objekt ScriptForge.Dictionary zurück, das alle Einträge enthält. Belegstatistiken sind enthalten. Beachten Sie, dass sie für den Dokumenttyp spezifisch sind. Beispielsweise enthält ein Calc-Dokument einen Eintrag "CellCount". Andere Dokumente nicht.
DocumentType | Ja | String | Zeichenfolge mit dem Dokumenttyp ("Base", "Calc", "Writer", …)
IsBase IsCalc IsDraw IsImpress IsMath IsWriter | Ja | Boolean | Genau eine dieser Eigenschaften ist für ein bestimmtes Dokument True.
Keywords (*) | Nein | String | Ermöglicht den Zugriff auf die Schlüsselwort-Eigenschaft des Dokuments. Dargestellt als durch Kommas getrennte Liste von Schlüsselwörtern
Readonly (*) | Ja | Boolean | True, wenn das Dokument tatsächlich im schreibgeschützten Modus ist
Subject (*) | Nein | String | Ermöglicht den Zugriff auf die Themen-Eigenschaft des Dokuments.
Title (*) | Nein | String | Ermöglicht den Zugriff auf die Titel-Eigenschaft des Dokuments.
XComponent | Ja | UNO-Objekt | Das UNO-Objekt com.sun.star.lang.XComponent oder com.sun.star.comp.dba .ODatabaseDocument, welches das Dokument darstellt

### Beispiel:

##### In Basic

Das folgende Beispiel druckt alle Eigenschaften eines Dokuments. Beachten Sie, dass das von der Methode UI.OpenDocument zurückgegebene Objekt oDoc ein Objekt vom Typ SFDocuments.Document ist.

        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

Um auf Dokumenteigenschaften in einem Python-Skript zuzugreifen, muss der Benutzer direkt mit seinen Namen darauf zugreifen, wie unten gezeigt:

        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()

Liste der Methoden im Dienst "Document"
Activate CloseDocument ExportAsPDF | PrintOut RunCommand Save | SaveAs SaveCopyAs SetPrinter

## Activate

Gibt True zurück, wenn das Dokument aktiviert werden konnte. Ansonsten ändert sich nichts an der eigentlichen Benutzeroberfläche. Sie entspricht der Methode Activate des Dienstes UI.

Diese Methode ist nützlich, wenn man den Fokus auf ein minimiertes oder ausgeblendetes Dokument legen muss.

### Syntax:

svc.Activate(): bool

### Beispiel:

Das folgende Beispiel geht davon aus, dass die Datei "My_File.ods" bereits geöffnet, aber nicht aktiv ist.

##### In Basic

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

##### In Python

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

Denken Sie daran, dass Sie den Dienst Document aufrufen können, indem Sie entweder "Document" oder "SFDocuments.Document" an CreateScriptService übergeben.

## CloseDocument

Schließt das Dokument. Wenn das Dokument bereits geschlossen ist, hat diese Methode unabhängig davon, wie das Dokument geschlossen wurde, keine Auswirkung und gibt False zurück.

Die Methode gibt auch False zurück, wenn der Benutzer sich weigert, sie zu schließen.

Gibt True zurück, wenn das Dokument erfolgreich geschlossen wurde.

### Syntax:

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

### Parameter:

saveask: Wenn True (Standard), wird der Benutzer aufgefordert zu bestätigen, ob die Änderungen auf die Festplatte geschrieben werden sollen. Dieses Argument wird ignoriert, wenn das Dokument nicht geändert wurde.

### Beispiel:

##### In Basic

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

##### In Python

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

## ExportAsPDF

Exportiert das Dokument direkt als PDF-Datei an den angegebenen Speicherort. Gibt True zurück, wenn die PDF-Datei erfolgreich erstellt wurde.

Die Exportoptionen können entweder manuell über den Dialog Datei – Exportieren als – Als PDF exportieren… oder durch Aufruf der Methoden GetPDFExportOptions und SetPDFExportOptions aus dem Dienst Session verwendet werden.

### Syntax:

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

### Parameter:

filename: Der vollständige Pfad und Dateiname der zu erstellenden PDF-Datei. Er muss der Notation SF_FileSystem.FileNaming folgen.

overwrite: Gibt an, ob die Zieldatei überschrieben werden kann (Standard = False). Ein Fehler tritt auf, wenn overwrite auf False gesetzt ist und die Zieldatei bereits existiert.

pages: Zeichenfolge, die angibt, welche Seiten exportiert werden. Dieses Argument verwendet die gleiche Schreibweise wie im Dialog Datei – Exportieren als – Als PDF exportieren….

password: Legt ein Kennwort zum Öffnen der PDF-Datei fest.

watermark: Als Wasserzeichen in der PDF-Datei zu verwendender Text, der auf jeder Seite des resultierenden PDFs gezeichnet wird.

### Beispiel:

##### In Basic

Das folgende Beispiel exportiert das aktuelle Dokument als PDF-Datei, definiert ein Kennwort und überschreibt die Zieldatei, falls diese bereits vorhanden ist.

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

Das folgende Code-Schnipsel fragt die aktuellen PDF-Exportoptionen ab und verwendet sie zum Erstellen der PDF-Datei.

        Dim exportSettings as Object, oSession as Object
        oSession = CreateScriptService("Session")
        exportSettings = oSession.GetPDFExportOptions()
        ' Setzt die Option zum Exportieren von Kommentaren als PDF-Notizen auf True
        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

Diese Methode sendet den Inhalt des Dokuments an den Standarddrucker oder an den durch die Methode SetPrinter definierten Drucker.

Gibt True zurück, wenn das Dokument erfolgreich gedruckt wurde.

### Syntax:

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

### Parameter:

pages: Die Seiten als Zeichenfolge, die gedruckt werden sollen, wie in der Benutzeroberfläche. Beispiel: "1-4;10;15-18". Standard ist alle Seiten.

copies: Die Anzahl der Kopien. Standard ist 1.

### Beispiel:

##### 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

Führt einen Befehl für ein Dokument aus. Der Befehl wird ohne Argumente ausgeführt.

Einige typische Befehle sind: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste, …

Das Dokument selbst muss nicht aktiv sein, um Befehle ausführen zu können.

### Syntax:

svc.RunCommand(command: str)

### Parameter:

command: Groß-/Kleinschreibung beachtende Zeichenfolge, die den Befehl in Englisch enthält. Der Befehl selbst wird nicht auf Korrektheit überprüft. Wenn nach dem Befehlsaufruf nichts passiert, dann ist der Befehl wahrscheinlich falsch.

### Beispiel:

Das folgende Beispiel führt den Befehl "SelectData" in einer Calc-Tabelle mit dem Namen "MyFile.ods" aus, was zur Auswahl des Datenbereichs basierend auf der aktuell ausgewählten Zelle führt.

##### In Basic

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

##### In Python

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

Das obige Beispiel führt tatsächlich den UNO-Befehl .uno:SelectData aus. Um die Methode RunCommand zu verwenden, muss daher die Teilzeichenfolge ".uno:" entfernt werden.

Jede LibreOffice-Komponente verfügt über einen eigenen Befehlssatz. Eine einfache Möglichkeit, Befehle zu lernen, ist der Aufruf von Extras > Anpassen… > Register: Tastatur. Wenn Sie Ihre Maus über eine Funktion in der Liste Funktion bewegen, erscheint ein Hilfetext mit dem entsprechenden UNO-Befehl.

## Save

Speichert das Dokument an dem Dateispeicherort, von dem es geladen wurde. Die Methode wird ignoriert, wenn das Dokument nicht geändert wurde.

Gibt False zurück, wenn das Dokument nicht gespeichert werden konnte. Ein Fehler wird ausgelöst, wenn die Datei schreibgeschützt geöffnet ist oder wenn es sich um eine neue Datei handelt, die noch nicht gespeichert wurde.

Das Dokument selbst muss nicht aktiv sein, um diese Methode auszuführen.

### Syntax:

svc.Save(): bool

### Beispiel:

##### In Basic

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

##### In Python

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

## SaveAs

Speichert das Dokument am angegebenen Dateispeicherort. Der neue Speicherort wird zum neuen Dateinamen, auf den einfache Methodenaufrufe "Save" angewendet werden.

Gibt False zurück, wenn das Dokument nicht gespeichert werden konnte. Ein Fehler wird ausgelöst, wenn das Überschreiben des Ziels abgelehnt wird oder wenn das schreibgeschützte Attribut des Ziels gesetzt ist.

Das Dokument selbst muss nicht aktiv sein, um diese Methode auszuführen.

### Syntax:

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

### Parameter:

filename: Eine Zeichenfolge, die den zu verwendenden Dateinamen enthält. Sie muss der Notation SF_FileSystem.FileNaming folgen.

overwrite: Wenn True, darf die Zieldatei überschrieben werden (Standard = False).

password (*): Eine Zeichenfolge ohne Leerzeichen zum Schutz des Dokuments.

filtername (*): Der Name eines Filters, der zum Speichern des Dokuments verwendet werden soll. Wenn dieses Argument übergeben wird, muss der Filter vorhanden sein.

filteroptions (*): Eine optionale Zeichenfolge mit Optionen, die dem Filter zugeordnet sind.

### Beispiel:

##### In Basic

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

##### In Python

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

## SaveCopyAs

Speichert eine Kopie des Dokuments oder exportiert es an den angegebenen Speicherort. Der tatsächliche Standort bleibt unverändert.

Gibt False zurück, wenn das Dokument nicht gespeichert werden konnte. Ein Fehler wird ausgelöst, wenn das Überschreiben des Ziels abgelehnt wird oder wenn das Attribut schreibgeschützt des Ziels gesetzt ist.

Das Dokument selbst muss nicht aktiv sein, um diese Methode auszuführen.

### Syntax:

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

### Parameter:

filename: Eine Zeichenfolge, die den zu verwendenden Dateinamen enthält. Sie muss der Notation SF_FileSystem.FileNaming folgen.

overwrite: Wenn True, darf die Zieldatei überschrieben werden (Standard = False).

password (*): Eine Zeichenfolge ohne Leerzeichen zum Schutz des Dokuments.

filtername (*): Der Name eines Filters, der zum Speichern des Dokuments verwendet werden soll. Wenn dieses Argument übergeben wird, muss der Filter vorhanden sein.

filteroptions (*): Eine optionale Zeichenfolge mit Optionen, die dem Filter zugeordnet sind.

### Beispiel:

##### In Basic

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

##### In Python

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

## SetPrinter

Definiert die Druckeroptionen für das Dokument.

Gibt bei Erfolg True zurück.

### Syntax:

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

### Parameter:

printer: Der Name der Druckerwarteschlange, auf der gedruckt werden soll. Bei Fehlen wird der Standarddrucker verwendet.

orientation: Entweder PORTRAIT oder LANDSCAPE. Wenn nicht vorhanden, wird in Bezug auf die Druckereinstellungen unverändert belassen.

paperformat: Gibt das Papierformat als Zeichenfolge an, der entweder A3, A4, A5, LETTER, LEGAL oder TABLOID sein kann. Bleibt bei Abwesenheit unverändert.

### Beispiel:

##### In Basic

        oDoc.SetPrinter(Orientation := "PORTRAIT")

##### In Python

        doc.SetPrinter(paperformat='TABLOID')

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Verwandte Themen

Dienst ScriptForge.UI

Dienst ScriptForge.Dictionary