Inhoud
Index 🔎︎

# SFDocuments.Document-service

De bibliotheek SFDocuments biedt methoden en eigenschappen om het beheer en de manipulatie van LibreOffice-documenten te vergemakkelijken.

Methoden die van toepassing zijn op alle soorten documenten (tekstdocumenten, bladen, presentaties, enz.) worden geleverd door de service SFDocuments.Document. Enkele voorbeelden zijn:

- Documenten openen, sluiten en opslaan

- Toegang tot standaard- of aangepaste eigenschappen van documenten

De eigenschappen, methoden of argumenten gemarkeerd met (*) zijn NIET van toepassing op Basic-documenten.

Methoden en eigenschappen die specifiek zijn voor bepaalde LibreOffice-componenten worden opgeslagen in afzonderlijke services, zoals SFDocuments.SF_Calc en SFDocuments.SF_Base.

Hoewel de Basic-taal geen overerving tussen objectklassen biedt, kunnen de laatstgenoemde services worden beschouwd als subklassen van de SFDocuments.Document-service. Dergelijke subklassen kunnen een beroep doen op de eigenschappen en methoden die hieronder worden beschreven.

## Service aanroep

Hieronder staan drie varianten van hoe de service Document kan worden aangeroepen.

##### In BASIC

Met behulp van de getDocument-methode van de ScriptForge.UI-service:

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

Als alternatief kunt u de methoden CreateDocument en OpenDocument van de UI-service gebruiken.

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

Direct als het document al geopend is.

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

Van een macro die is geactiveerd door een documentgebeurtenis.

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

De service Document is nauw verwant aan de services UI en FileSystem.

Behalve wanneer het document werd afgesloten door een programma met de CloseDocument-methode (het is dan overbodig), wordt aanbevolen om na gebruik bronnen vrij te maken:

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

Het gebruik van het voorvoegsel "SFDocuments." tijdens het aanroepen van de service is optioneel.

## Eigenschappen

Naam | AlleenLezen | Type | Beschrijving
CustomProperties (*) | Nee | Dictionary service | Retourneert een objectinstantie ScriptForge.Dictionary. Na update kan het opnieuw worden doorgegeven aan de eigenschap om het document bij te werken. Individuele items van het woordenboek kunnen strings, cijfers, (basis)datums of com.sun.star.util.Duration items.
Description (*) | Nee | String | Geeft toegang tot de eigenschap Beschrijving van het document (ook bekend als "Notities")
DocumentProperties (*) | Ja | Dictionary service | Retourneert een ScriptForge.Dictionary-object dat alle vermeldingen bevat. Documentstatistieken zijn inbegrepen. Merk op dat ze specifiek zijn voor het type document. Een Calc-document bevat bijvoorbeeld een invoer "CellCount". Andere documenten niet.
DocumentType | Ja | String | Tekenreeks met het documenttype ("Base", "Calc", "Writer", enz.)
IsBase IsCalc IsDraw IsImpress IsMath IsWriter | Ja | Boolean | Precies één van deze eigenschappen is True voor een bepaald document.
Keywords (*) | Nee | String | Geeft toegang tot de eigenschap Trefwoorden van het document. Weergegeven als een door komma's gescheiden lijst met trefwoorden
Readonly (*) | Ja | Boolean | True als het document zich in de alleen-lezen modus bevindt
Subject (*) | Nee | String | Geeft toegang tot de eigenschap Onderwerp van het document.
Title (*) | Nee | String | Geeft toegang tot de eigenschap Titel van het document.
XComponent | Ja | UNO-object | Het UNO-object com.sun.star.lang.XComponent of com.sun.star.comp.dba .ODatabaseDocument dat het document vertegenwoordigt

### Voorbeeld:

##### In BASIC

In het onderstaande voorbeeld worden alle eigenschappen van een document afgedrukt. Merk op dat het oDoc-object dat wordt geretourneerd door de UI.OpenDocument-methode, een SFDocuments.Document-object is.

        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

Om toegang te krijgen tot documenteigenschappen in een Python-script, moet de gebruiker deze rechtstreeks openen met behulp van hun naam, zoals hieronder weergegeven:

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

Lijst met methoden in de Documentenservice
Activate CloseDocument ExportAsPDF | PrintOut RunCommand Save | SaveAs SaveCopyAs SetPrinter

## Activate

Retourneert True als het document zou kunnen worden geactiveerd. Anders is er geen verandering in de eigenlijke gebruikersinterface. Het is gelijk aan de Activate-methode van de UI-service.

Deze methode is handig wanneer men focus moet geven aan een document dat geminimaliseerd of verborgen is.

### Syntaxis:

svc.Activate(): bool

### Voorbeeld:

In het onderstaande voorbeeld wordt ervan uitgegaan dat het bestand "My_File.ods" al open maar niet actief is.

##### In BASIC

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

##### In Python

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

Houd er rekening mee dat u de service Document kunt aanroepen door "Document" of "SFDocuments.Document" door te geven aan CreateScriptService

## CloseDocument

Sluit het document. Als het document al is gesloten, ongeacht hoe het document is gesloten, heeft deze methode geen effect en retourneert False.

De methode retourneert ook False als de gebruiker weigert deze te sluiten.

Retourneert True als het document met succes is gesloten.

### Syntaxis:

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

### Parameters:

saveask : Indien True (standaard), wordt de gebruiker uitgenodigd om te bevestigen of de wijzigingen op schijf moeten worden geschreven. Dit argument wordt genegeerd als het document niet is gewijzigd.

### Voorbeeld:

##### In BASIC

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

##### In Python

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

## ExportAsPDF

Exporteert het document rechtstreeks als PDF-bestand naar de opgegeven locatie. Retourneert True als het PDF-bestand met succes is gemaakt.

De exportopties kunnen handmatig worden ingesteld met behulp van het dialoogvenster Bestand - Exporteren als - Exporteren als PDF of door de methoden GetPDFExportOptions en SetPDFExportOptions aan te roepen vanuit de Sessie-service.

### Syntaxis:

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

### Parameters:

filename: Het volledige pad en de bestandsnaam van de te maken PDF. Het moet de notatie SF_FileSystem.FileNaming volgen.

overwrite: Geeft aan of het doelbestand kan worden overschreven (Standaard = False). Er zal een fout optreden als overwrite is ingesteld op False en het doelbestand al bestaat.

pages: tekenreeks die aangeeft welke pagina's worden geëxporteerd. Dit argument gebruikt dezelfde notatie als in het dialoogvenster Bestand - Exporteren als - Exporteren als PDF.

password: Specificeert een wachtwoord om het PDF-bestand te openen.

watermark: Tekst die moet worden gebruikt als watermerk in het PDF-bestand, dat op elke pagina van de resulterende PDF wordt getekend.

### Voorbeeld:

##### In BASIC

Het volgende voorbeeld exporteert het huidige document als een PDF-bestand, definieert een wachtwoord en overschrijft het doelbestand als dit al bestaat.

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

Het onderstaande codefragment haalt de huidige PDF-exportopties op en gebruikt deze om het PDF-bestand te maken.

        Dim exportSettings as Object, oSession as Object
        oSession = CreateScriptService("Session")
        exportSettings = oSession.GetPDFExportOptions()
        ' Stelt de optie in om opmerkingen als PDF-notities te exporteren op 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

Deze methode stuurt de inhoud van het document naar de standaardprinter of naar de printer die is gedefinieerd door de SetPrinter-methode.

Retourneert True als het document is afgedrukt.

### Syntaxis:

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

### Parameters:

pages: De pagina's die als een tekenreeks moeten worden afgedrukt, zoals in de gebruikersinterface. Voorbeeld: "1-4;10;15-18". Standaard is dit alle pagina's.

copies: Het aantal exemplaren. Standaard is 1.

### Voorbeeld:

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

Voert een commando op een document uit. Het commando heeft geen argumenten.

Een paar voorbeelden zijn: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy en Paste.

Het document zelf hoeft niet actief te zijn om opdrachten te kunnen uitvoeren.

### Syntaxis:

svc.RunCommand(command: str)

### Parameters:

command: Hoofdlettergevoelige tekenreeks met het commando in het Engels. Het commando wordt niet gecontroleerd. Als er na de aanroep niets lijkt te gebeuren dan was het commando waarschijnlijk fout.

### Voorbeeld:

In dit voorbeeld wordt het commando "SelectData" commando in een Calc-bestand "MyFile.ods" uitgevoerd, wat resulteert in de selectie van een aantal cellen gebaseerd op de huidige geselecteerde cel.

##### In BASIC

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

##### In Python

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

In het bovenstaande voorbeeld wordt het UNO-commando .uno:SelectData uitgevoerd. Om de RunCommand methode te gebruiken is het dus nodig om de ".uno:" substring te verwijderen.

Elk LibreOffice-component heeft zijn eigen set beschikbare commando's. Om ze te leren kennen kunt u via Extra > Aanpassen > Toetsenbord de lijst Functie zien. Als u daar met de muis overheen gaat ziet u een tip met het overeenkomende UNO-commando.

## Save

Slaat het document op op de bestandslocatie van waaruit het is geladen. De methode wordt genegeerd als het document niet is gewijzigd.

Retourneert False als het document niet kon worden opgeslagen. Er wordt een foutmelding gegeven als het bestand als alleen-lezen is geopend of als het een nieuw bestand is dat nog niet is opgeslagen.

Het document zelf hoeft niet actief te zijn om deze methode uit te voeren.

### Syntaxis:

svc.Save(): bool

### Voorbeeld:

##### In BASIC

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

##### In Python

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

## SaveAs

Slaat het document op de opgegeven bestandslocatie op. De nieuwe locatie wordt de nieuwe bestandsnaam waarop eenvoudige methodeaanroepen Save worden toegepast.

Retourneert False als het document niet kon worden opgeslagen. Er treedt een fout op wanneer het overschrijven van de bestemming wordt afgewezen of wanneer het alleen-lezen kenmerk van de bestemming is ingesteld.

Het document zelf hoeft niet actief te zijn om deze methode uit te voeren.

### Syntaxis:

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

### Parameters:

filename: Een tekenreeks die de bestandsnaam bevat die moet worden gebruikt. Het moet de notatie SF_FileSystem.FileNaming volgen.

overwrite: Indien True, kan het doelbestand worden overschreven (default = False).

password (*): Een tekenreeks zonder spatie om het document te beschermen.

filtername (*): De naam van een filter dat moet worden gebruikt om het document op te slaan. Als dit argument wordt doorgegeven, moet het filter bestaan.

filteroptions (*): Een optionele tekenreeks met opties die aan het filter zijn gekoppeld.

### Voorbeeld:

##### In BASIC

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

##### In Python

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

## SaveCopyAs

Slaat een kopie op van of exporteer het document naar de opgegeven bestandslocatie. De werkelijke locatie is ongewijzigd.

Retourneert False als het document niet kon worden opgeslagen. Er treedt een fout op wanneer het overschrijven van de bestemming wordt afgewezen of wanneer het alleen-lezen kenmerk van de bestemming is ingesteld.

Het document zelf hoeft niet actief te zijn om deze methode uit te voeren.

### Syntaxis:

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

### Parameters:

filename: Een tekenreeks die de bestandsnaam bevat die moet worden gebruikt. Het moet de notatie SF_FileSystem.FileNaming volgen.

overwrite: Indien True, kan het doelbestand worden overschreven (standaard = False).

password (*): Een tekenreeks zonder spatie om het document te beschermen.

filtername (*): De naam van een filter dat moet worden gebruikt om het document op te slaan. Als dit argument wordt doorgegeven, moet het filter bestaan.

filteroptions (*): Een optionele tekenreeks met opties die aan het filter zijn gekoppeld.

### Voorbeeld:

##### In BASIC

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

##### In Python

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

## SetPrinter

Definieert de printeropties voor het document.

Retourneert True indien succesvol.

### Syntaxis:

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

### Parameters:

printer: De naam van de printerwachtrij waarnaar moet worden afgedrukt. Indien afwezig is de standaardprinter ingesteld.

orientation: Ofwel PORTRAIT of LANDSCAPE. Blijft onveranderd indien afwezig, met betrekking tot de printerinstellingen.

paperformat: Specificeert het papierformaat als een tekenreekswaarde die A3, A4, A5, LETTER, LEGAL of TABLOID kan zijn. Blijft onveranderd indien afwezig.

### Voorbeeld:

##### In BASIC

        oDoc.SetPrinter(Orientation := "PORTRAIT")

##### In Python

        doc.SetPrinter(paperformat='TABLOID')

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Verwante onderwerpen

Service ScriptForge.UI

ScriptForge.Dictionary dienst