Innhald
Innhaldsliste 🔎︎

# Tenesta SFDocuments.Document

Biblioteket SFDocuments gjev metodar og eigenskapar for å letta handsaming og manipulering av LibreOffice-dokument.

Metodar som kan brukast på alle typar av dokument (tekstdokument, rekneark, presentasjonar og så vidare) vert leverte av tenesta SFDocuments.Document. Nokre eksempel er:

- Opning, lukking og lagring av dokument

- Tilgang til standard eller tilpassa eigenskapar for dokumenta

Dei eigenskapane, metodane eller argumenta som er merkte med (*) kan IKKJE brukast på database-dokument.

Metodar og eigenskapar som er spesifikke for LibreOffice-komponentar vert lagra i åtskilde tenester, som for eksempel SFDocuments.SF_Calc og SFDocuments.SF_Base.

Sjølv om Basic-språket ikkje tilbyr nedarving mellom objektklassar, kan objektklassane sjåast på som underklasser av tenesta SFDocuments.Document. Slike underklassar kan kalla opp dei eigenskapane og metodane som er omtalte nedanfor.

## Oppkall av tenester

Nedanfor finn du tre ulike måtar å kalla opp tenesta Document.

##### I Basic

Med metoden getDocument frå tenesta ScriptForge.UI:

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

Du kan også bruka metodane CreateDocument og OpenDocument frå tenesta UI.

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

Direkte viss dokumentet alt er opna.

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

Frå ein makro utløyst av ei dokument-hending.

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

Tenesta Document er i nær slekt med tenestene UI og FileSystem.

Bortsett frå når dokumentet vart lukka av eit program med CloseDocument-metoden (det er då overflødig),vert det tilrådd å frigjera ressursar etter bruk:

        Set oDoc = oDoc.Dispose()

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

Bruk av prefikset «SFDocuments.» ved oppkall av tenesta er frivillig.

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
CustomProperties (*) | Nei | Dictionary service | Returnerer ein objektførekomst frå ScriptForge.Dictionary. Etter ei oppdatering kan den igjen sendast til den gjeldande eigenskapen som oppdaterer dokumentet. Individuelle element i ordboka kan vera anten strenge, tal, (Basic-)dato eller com.sun.star.util.Duration-element.
Description (*) | Nei | String | Gjev tilgang til dokumenteigenskapen Description (også kjend som «Nerknadar»)
DocumentProperties (*) | Ja | Dictionary service | Returnerer eit ScriptForge.Dictionary-objekt som inneheld alle oppføringane. Dokumentstatistikk er inkludert. Legg merke til at dei er spesifikke for dokumenttypen. For eksempel inneheld eit Calc-dokument ei CellCount-oppføring. Andre dokument gjer det ikkje.
DocumentType | Ja | String | Strengverdi med dokumenttypen («Base», «Calc», «Writer» og så vidare)
IsBase IsCalc IsDraw IsImpress IsMath IsWriter | Ja | Boolean | Nøyaktig éin av desse eigenskapane er Sann for eit gjeve dokument.
Keywords (*) | Nei | String | Gjev tilgang til nøkkelordeigenskapen for dokumentet. Representert som ei kommadelt liste over nøkkelord
Readonly (*) | Ja | Boolean | True viss dokumentet faktisk er i skriveverna tilstand
Subject (*) | Nei | String | Gjev tilgang til emne-eigenskapen for dokumentet.
Title (*) | Nei | String | Gjev tilgang til tittel-eigenskapen for dokumentet.
XComponent | Ja | UNO-objekt | UNO-objektet com.sun.star.lang.XComponent eller com.sun.star.comp.dba.ODatabaseDocument, som representerer dokumentet

### Eksempel:

##### I Basic

Eksempelet nedanfor skriv ut alle eigenskapane brukte i dokument. Merk at objektet oDoc, som vert returnert av metoden UI.OpenDocument, er eit SFDocuments.Document-objekt.

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

##### I Python

For få tilgang til dokumenteigenskapar i eit Python-skript som brukaren treng for å få direkte tilgang til dei ved hjelp av namna, som vist nedanfor:

        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 over metodar i tenesta document
Activate CloseDocument ExportAsPDF | PrintOut RunCommand Save | SaveAs SaveCopyAs SetPrinter

## Activate

Returnerer Sann viss dokumentet kunne aktiverast. Elles er det inga endring i det faktiske brukargrensesnittet. Det svarar til metoden Activate i tenesta UI.

Denne metoden er nyttig når ein må fokusera på eit dokument som er minimert eller gøymd.

### Syntaks:

svc.Activate(): bool

### Eksempel:

Eksempelet nedanfor finn at fila «Mi_Fil.ods» alt er opna, men ikkje aktiv.

##### I Basic

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

##### I Python

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

Hugs at du kan kalla opp tenesta Document ved å overføra anten «Document» eller «SFDocuments.Document» til tenesta CreateScriptService

## CloseDocument

Lukker dokumentet. Viss dokumentet alt er lukka, same korleis, har denne metode ingen verknad og returnerer Usann.

Metoden returnerer også Usann viss brukaren avviser å lukka han.

Returnerer Sann viss det lukkast å lukka dokumentet.

### Syntaks:

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

### Parametrar:

saveask: Viss Sann (standard) vert brukaren beden om å stadfesta om endringane skal skrivast til lagringsmediumet. Argumentet vert ignorert om det ikkje er gjort endringar i dokumentet.

### Eksempel:

##### I Basic

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

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

### Syntaks:

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

### Parametrar:

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.

### Eksempel:

##### I 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")

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

### Syntaks:

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

### Parametrar:

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.

### Eksempel:

##### I Basic

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

##### I Python

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

## RunCommand

Køyrer ein kommando på eit dokument. Kommandoen vert utført utan argument.

Nokre få typiske kommandoar er Lagra, Lagra som, EksporterTilPDF, SetDokumenteigenskapar, Angra, Kopier, Sett inn og så vidare.

Dokumentet treng ikkje vera aktivt for å kunna køyra kommandoar.

### Syntaks:

svc.RunCommand(command: str)

### Parametrar:

kommando: Streng, som skil mellom store og små bokstavar, med kommandoen på engelsk. Det vert ikkje kontrollert at strengen er korrekt. Viss det ikkje skjer noko etter oppkallet med kommandoen, er ham sannsynlegvis feil.

### Eksempel:

Eksempelet nedanfor køyrer «SelectData»-kommandoen i eit Calc-ark kalla «MiFil.ods», som vil resultere i val av dataområdet basert på den merkte cella.

##### I Basic

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

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

Kvar LibreOffice-komponent har tilgang til sitt eige kommando-sett. Ein grei måte å læra kommandoane på, er å gå til Verktøy → Tilpass → Tastatur. Når du set musa over ein funksjon på lista Funksjon, vert det vist eit verktøytips saman med den tilsvarande UNO-kommandoen.

## Save

Lagrar dokumentet der det vart henta frå. Metoden vert ignorert viss dokumentet ikkje er endra.

Returnerer Usann viss dokumentet ikkje kan lagrast. Det vert sett opp ein feil viss fila er opna som skriveverna eller viss det er ei ny fil utan namn.

Dokumentet treng ikkje vera aktivt for å bruk denne metoden.

### Syntaks:

svc.Save(): bool

### Eksempel:

##### I Basic

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

##### I Python

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

## SaveAs

Lagrar dokumentet i den gjevne filplasseringa. Den nye plasseringa vert det nye filnamnet som vert brukt av det enkle metodekallet «Lagra».

Returnerer Usann viss dokumentet ikkje kan lagrast. Der vert sett opp ein feil viss målet ikkje kan overskrivast eller når målet er skriveverna.

Dokumentet treng ikkje vera aktivt for å bruk denne metoden.

### Syntaks:

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

### Parametrar:

filnamn: Ein streng som inneheld det filnamnet som skal brukast. Namnet må følgja notasjonen SF_FileSystem.FileNaming.

overskriv: Viss Sann kan målfila overskrivast (standard = Usann.

passord (*): Ein streng utan mellomrom som skal brukast for å verna dokumentet.

filternamn (*): Namnet på eit filter som skal brukast for å lagra dokumentet. Viss argumentet vert sendt vidare, må filteret finnast.

filterinnstillingar (*): Ein valfri streng med innstillingar for dette filteret.

### Eksempel:

##### I Basic

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

##### I Python

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

## SaveCopyAs

Lagrar ein kopi eller eksporterer dokumentet til den gjevne filplasseringa. Den aktuelle plasseringa vert ikkje endra.

Returnerer Usann viss dokumentet ikkje kan lagrast. Der vert sett opp ein feil viss målet ikkje kan overskrivast eller når målet er skriveverna.

Dokumentet treng ikkje vera aktivt for å bruk denne metoden.

### Syntaks:

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

### Parametrar:

filnamn: Ein streng som inneheld det filnamnet som skal brukast. Namnet må følgja notasjonen SF_FileSystem.FileNaming.

overskriv: Viss Sann kan målfila overskrivast (standard = Usann.

passord (*): Ein streng utan mellomrom som skal brukast for å verna dokumentet.

filternamn (*): Namnet på eit filter som skal brukast for å lagra dokumentet. Viss argumentet vert sendt vidare, må filteret finnast.

filterinnstillingar (*): Ein valfri streng med innstillingar for dette filteret.

### Eksempel:

##### I Basic

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

##### I Python

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

## SetPrinter

Defines the printer options for the document.

Returns True when successful.

### Syntaks:

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

### Parametrar:

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.

### Eksempel:

##### I Basic

        oDoc.SetPrinter(Orientation := "PORTRAIT")

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

Liknande emne

Tenesta ScriptForge.UI

Tenesta ScriptForge.Dictionary