Tjenesten SFDocuments.Document

Biblioteket SFDocuments leverer metoder og egenskaber til at lette hÄndtering og manipulation af LibreOffice dokumenter.

Metoder, der kan anvendes pÄ alle typer af dokumenter (tekstdokumenter, regneark, prÊsentationer og sÄ videre) leveres af tjenesten SFDocuments.Document. Nogle eksempler er:

warning

De egenskaber, metoder eller argumenter, der er markeret med (*) er IKKE anvendelige pÄ database-dokumenter.


Metoder og egenskaber, der er specifikke for LibreOffice-programmer gemmes i sĂŠrlige tjenester, som for eksempel SFDocuments.SF_Calc og SFDocuments.SF_Base.

Selv om Basic-sproget ikke tilbyder nedarvning mellem objektklasser, kan de sidstnÊvnte anses som underklasser af tjenesten SFDocuments.Document. SÄdanne underklasser kan kalde de egenskaber og metoder, der beskrives herunder.

Kald af tjeneste

Herunder er der tre forskellige mÄder at kalde tjenesten Document pÄ.

I Basic

Med metoden getDocument fra tjenesten ScriptForge.UI:


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

Alternativt kan du bruge metoderne CreateDocument og OpenDocument fra tjenesten UI.


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

Direkte, hvis dokumentet allerede er Äbent.


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

Fra en makro udlĂžst af en dokument-hĂŠndelse.


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

Tjenesten Document er tĂŠt beslĂŠgtet med tjenesterne UI og FileSystem.


Undtaget, nÄr dokumentet blev lukket med et program med metoden CloseFocument (hvor det er overflÞdigt), anbefales det at frigÞre ressourcer efter brug:


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

Brug af forstavelsen "SFDocuments." under kald af tjenesten er frivillig.


Egenskaber

Navn

Skrivebeskyttet

Type

Beskrivelse

CustomProperties (*)

Nej

Dictionary service

Returnerer en objektforekomst fra ScriptForge.Dictionary. Efter en opdatering kan den igen sendes til den egenskab, der opdaterer dokumentet.
Individuelle elemernter i ordbogen, kan vĂŠre enten strenge, tal, (Basic-)datoer eller com.sun.star.util.Duration-elementer.

Description (*)

Nej

String

Giver adgang til dokumentegenskaben Beskrivelse (ogsÄ kendt som "Kommentarer")

DocumentProperties (*)

Ja

Dictionary service

Returnerer et ScriptForge.Dictionary-objekt, der indeholder alle indfĂžrslerne. Dokumentets statitisk medtages. BemĂŠrk, at de er specifikke for dokumenttypen. Eksempelvis medtager et Calc-dokument elementet "CelleOptĂŠlling". Andre dokumenter gĂžr det ikke.

DocumentType

Ja

String

StrengvÊrdi med dokumenttypen ("Base", "Calc", "Writer" og sÄ videre)

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

Ja

Boolean

PrĂŠcis en af disse egenskaber er True for et givet dokument.

Keywords (*)

Nej

String

Giver adgang til dokumentegenskaben NĂžgleord. ReprĂŠsenteres som en komma-separeret liste over nĂžgleord

Readonly (*)

Ja

Boolean

True hvis dokumentet faktisk er i skrivebeskyttet tilstand

Subject (*)

Nej

String

Giver adgang til dokumentegenskaben Emne

Title (*)

Nej

String

Giver adgang til dokumentegenskaben Titel

XComponent

Ja

UNO-objekt

UNO-objektet com.sun.star.lang.XComponent eller com.sun.star.comp.dba.ODatabaseDocument, der reprĂŠsenterer dokumentet


Eksempel:

I Basic

Eksemplet herunder udskriver alle dokumentets egenskaber. BemĂŠrk, at objektet oDoc, der returneres af metodenUI.OpenDocument er et 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 at tilgÄ dokumentegenskaber i et Python-script skal brugeren adressere dem direkte ved at bruge deres navne, som vist herunder:


    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 metoder i tjenesten Document

Activate
CloseDocument
ExportAsPDF

PrintOut
RunCommand
Save

SaveAs
SaveCopyAs
SetPrinter


Activate

Returnerer True, hvis dokumentet kunne aktiveres. Ellers sker der ingen ĂŠndring i den faktiske brugerflade. Den svarer til metoden Activate i tjenesten UI.

Denne metode er nyttig, nÄr man har brug fir at give fokus til et dokument, der minimeret eller skjult. when one needs to give focus for a document that is minimized or hidden.

Syntaks:

svc.Activate(): bool

Eksempel:

Eksemplet herunder finder, at filen "My_File.ods" allerede er Äben, men ikke aktiv.

I Basic

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

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

Husk pÄ, at du kan kalde tjenesten Document ved at overfÞre enten "Document" eller "SFDocuments.Document" til tjenesten CreateScriptService


CloseDocument

Lukker dokumentet. Hvis dokumentet allerede er lukket, uanset hvorden det blev lukket, har denne metode ingen virkning og returnerer False.

Metoden returnerer ogsÄ False, hvis brugeren afviser at lukke den.

Returnerer True, hvis det lykkedes at lukke dokumentet.

Syntaks:

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

Parametre:

gem_spĂžrg: HvisTrue (sand) (standard), bedes brugeren om at bekrĂŠfte, om ĂŠndringerne skal skrives til disken. Dette argument ignoreres, hvis dokumentet ikke blev ĂŠndret.

Eksempel:

I Basic

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

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

ExportAsPDF

Eksporterer dokumentet direkte som en PDF-fil til den angivne placering. Returnerer True (sand), hvis det lykkedes at oprette PDF-filen.

Eksportindstillinger kan séttes enten manuelt med dialogen Filer ▾ Eksporter som ▾ Eksporter som PDF eller ved at kalde metoderne GetPDFExportOptions (hent_PDF-eksport-indstillinger) og SetPDFExportOptions (sét_PDF-eksport-indstillinger) fra tjenesten Session.

Syntaks:

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

Parametre:

filnavn: Den fuldstÊndige sti og filnavn pÄ den PDF-fil, der skal oprettes. Det skal fÞlge notationen i SF_FileSystem.FileNaming.

overskriv: Angiver, om mÄlcellen kan overskrives (Standard = False - falsk). Der vil ske en fejl, hvis overwrite (overskriv) er sat til False (falsk) og mÄlfilen allerede eksisterer.

sider: Streng, der angiver, hvilke sider, der skal eksporteres. Dette argument bruger den samme notation som i dialogen Filer ▾ Eksporter som ▾ Eksporter som PDF.

adgangskode: Angiver en adgangskode til Äbning af PDF-filen.

vandmÊrke: Tekst, der skal bruges som vandmÊrke i PDF-filen og som bliver tegnet pÄ hver side i den resulterende PDF.

Eksempel:

I Basic

FÞlgende eksempel eksporterer det aktuelle dokument som en PDF-fil, definerer en adgangskode og overskriver mÄlfilen, hvis den allerede eksisterer.


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

Kodestumpen herunder henter de aktuelle PDF-eksportindstillinger og bruger dem til at oprette PDF-filen.


    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' SĂŠtter indstillingen for eksport af kommentarer som PDF-noter til True (sand).
    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

Denne metode sender dokumentets indhold til standardprinteren eller til den printer, der blev defineret med metoden SetPrinter.

Returnerer True (sand), hvis det lykkedes at udskrive dokumentet.

Syntaks:

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

Parametre:

sider: De sider, der skal udskrives, som en streng. ligesom i brugerfladen. Eksempel: "1-4;10;15-18". Standard er alle sider.

kopier: Antallet af kopier. Standard er 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Þrer en kommando pÄ et dokument. Kommandoen udfÞres uden argumenter.

Nogle fÄ typiske kommandoer er: Gem, GemSom, EksporterTilPDF, SÊtDokumentEgenskaber, Fortryd, Kopier, IndsÊt og sÄ videre.

Dokumentet selv behĂžver ikke at vĂŠre aktivt for at kunne kĂžre kommandoer.

Syntaks:

svc.RunCommand(command: str)

Parametre:

kommando: Streng med Stort-og-smÄt, der indeholder kommandoen pÄ engelsk. Kommandoen selv tjekkes ikke for korrekthed. Hvis der ikke sker noget efter kommando-kaldet, er kommando sandsynligvis forkert.

Eksempel:

Det fÞlgende eksempel kÞrer kommandoen "SelectData" i et Calc-regneark ved navn "MinFil.ods", som resulterer i markering af databaseomrÄdet, baseret pÄ den aktuelt valgte celle.

I Basic

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

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

Eksemplet herover kĂžrer faktisk UNO-kommandoen .uno:SelectData. Derfor er det nĂždvendigt at bruge metoden RunCommand (kĂžr_kommando) til at fjerne delstrengen ".uno:".

tip

Hvert LibreOffice-program har afgang til sit eget kommando-sĂŠt. En nem mĂ„de at lĂŠre kommandoerne pĂ„ er at gĂ„ til Funktioner ▾ Tilpas ▾ Tastatur. NĂ„r du placerer musen over en funktion pĂ„ listen Funktion, vises et vĂŠrktĂžjstip sammen med den tilsvarende UNO-kommando.


Save

Gemmer dokumentet pÄ den filplacering, det blev hentet fra. Metoden ignoreres, hvis dokumentet ikke blev Êndret.

Returnerer False (Falsk), hvis dokumentet ikke kunne gemmes. Der sÊttes et fejlflag, hvis filen er Äbnet som skrivebeskyttet, eller hvis det er en ny fil, der endnu ikke er blevet gemt.

Selve dokumentet behĂžver ikke at vĂŠre aktivt, for at kĂžre denne metode.

Syntaks:

svc.Save(): bool

Eksempel:

I Basic

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

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

SaveAs

Gemmer dokumentet pÄ den givne filplacering. Den nye placering bliver det nye filnavn, som simple metodekald Save (Gem) anvendes pÄ.

Returnerer False (Falsk), hvis dokumentet ikke kunne gemmes. Der sÊttes et fejlflag, hvis overskrivning af mÄlet afvises eller nÄr mÄlet har attributten Read-only (Skrivebeskyttet).

Selve dokumentet behĂžver ikke at vĂŠre aktivt for at kĂžre denne metode.

Syntaks:

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

Parametre:

fil_navn: En streng, der indeholder det filnavn, der skal bruges. Det skal fĂžlge notationen SF_FileSystem.FileNaming.

overskriv: Hvis True (sand), kan mÄlfilen blive overskrevet (standard = False (falsk)).

adgangskode (*): En streng uden mellemum, der skal beskytte dokumentet.

filter_navn (*): Navnet pÄ et filter, der skal bruges til at gemme dokumentet. Hvis argumentet gives videre, skal filteret eksistere.

filterindstillinger (*): En valgfri streng med indstillinger, der er forbundet med dette filter.

Eksempel:

I Basic

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

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

SaveCopyAs

Gemmer en kopi eller eksporterer dokumentet til den givne filplacering. Den faktiske placering er uĂŠndret.

Returnerer False (Falsk), hvis dokumentet ikke kunne gemmes. Der sÊttes et fejlflag, nÄr overskrivning af mÄlet afvises eller nÄr mÄlet har atrributten Read-only (Skrivebeskyttet).

Selve dokumentet behĂžver ikke at vĂŠre aktivt for at kĂžre denne metode.

Syntaks:

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

Parametre:

filnavn: En streng, der indholder det finavnl, der skal bruges. Det skal fĂžlge notationen iSF_FileSystem.FileNaming.

overskriv: Hvis True (sand), kan mÄlfilen blive overskrevet (Standard = False (falsk)).

adgangskode (*): En streng uden mellemrum, der skal beskytte dokumentet.

filternavn (*): Navnet pÄ et filter, der skal bruges til at gemme dokumentet. Hvis dette argument gives videre, skal filteret eksistere.

filterindstillinger (*): En valgfri streng, der er tilknyttet filteret.

Eksempel:

I Basic

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

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

SetPrinter

Definerer dokumentets printerindstillinger.

Returnerer True (sand), nÄr den lykkes.

Syntaks:

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

Parametre:

printer: Navnet pÄ den printerkÞ, der skal printes til. NÄr den mangler, sÊttes standardprinteren.

papirretning: Enten PORTRAIT (stÄende) eller LANDSCAPE (liggende). NÄr den mangler, efterlades feltet uÊndret med hensyn til printerindstillinger.

papirformat: Angiver papirformatet som en strengvĂŠrdi, som kan vĂŠre enten A3, A4, A5, LETTER, LEGAL eller TABLOID. Efterlades uĂŠndret, hvis manglende.

Eksempel:

I Basic

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
I Python

    doc.SetPrinter(paperformat='TABLOID')
  
warning

Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.