SFDocuments.Dokument tjeneste

SFDocuments-biblioteket gir metoder og egenskaper for Ă„ forenkle administrasjon og manipulering av LibreOfficeDev-dokumenter.

Metoder som kan brukes for alle typer dokumenter (tekstdokumenter, ark, presentasjoner osv.) leveres av SFDocuments.Document-tjenesten. Noen eksempler er:

warning

Egenskapene, metodene eller argumentene merket med (*) er IKKE gjeldende for basisdokumenter.


Metoder og egenskaper som er spesifikke for visse LibreOfficeDev-komponenter, lagres i separate tjenester, for eksempel SFDocuments.SF_Calc og SFDocuments.SF_Base.

Selv om Basic-sprÄket ikke tilbyr arv mellom objektklasser, kan sistnevnte tjenester betraktes som underklasser av SFDocuments.Document-tjenesten. Slike underklasser kan pÄkalle egenskapene og metodene beskrevet nedenfor.

TjenestepÄkallelse

FÞr du bruker Dokument-tjenesten, mÄ ScriptForge-biblioteket lastes eller importeres:

note

‱ Grunnleggende makroer krever Ă„ laste ScriptForge-biblioteket ved hjelp av fĂžlgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

‱ Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService


Nedenfor er tre varianter av hvordan Dokument-tjenesten kan pÄkalles.

I Basic

Ved Ă„ bruke getDocument-metoden fra ScriptForge.UI-tjenesten:


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

Alternativt kan du bruke metodene CreateDocument og OpenDocument fra UI-tjenesten.


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

Bruke et vindunavn hvis dokumentet allerede er Äpent.


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

Bruke dokumentet det refereres til av ThisComponent. Dette er spesielt nyttig nÄr du kjÞrer en makro fra Basic IDE.


    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", ThisComponent)
  

Fra en makro utlĂžst av en dokumenthendelse.


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

Dokument-tjenesten er nĂŠrt knyttet til UI og FileSystem-tjenestene.


Bortsett fra nÄr dokumentet ble lukket av program med CloseDocument-metoden (det er da overflÞdig), anbefales det Ä frigjÞre ressurser 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")
  

    bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisComponent)
  

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

Bruken av prefikset "SFDocuments." mens du anroper tjenesten er valgfritt.


Egenskaper

Navn

Skrivebeskyttet

Type

Beskrivelse

CustomProperties (*)

Nei

Dictionary service

Returnerer en ScriptForge.Dictionary objektforekomst. Etter oppdatering kan den sendes igjen til eiendommen for oppdatering av dokumentet.
Individuelle elementer i ordboken kan enten vĂŠre strenger, tall, (grunnleggende) datoer eller com.sun.star.util.Duration elementer.

Description (*)

Nei

String

Gir tilgang til beskrivelsesegenskapen til dokumentet (ogsÄ kjent som "Kommentarer")

DocumentProperties (*)

Ja

Dictionary service

Returnerer et ScriptForge.Dictionary-objekt som inneholder alle oppfĂžringene. Dokumentstatistikk er inkludert. Merk at de er spesifikke for dokumenttypen. Som et eksempel inkluderer et Calc-dokument en "CellCount"-oppfĂžring. Andre dokumenter gjĂžr det ikke.

DocumentType

Ja

String

Strengverdi med dokumenttypen ("Base", "Calc", "Writer", osv.)

ExportFilters

Ja

String array

Returnerer en liste med eksportfilternavnene som gjelder for gjeldende dokument, som en nullbasert matrise med strenger. Filtre brukt for bÄde import/eksport returneres ogsÄ.

FileSystem

Yes

String

Returns a string with the URL path to the root of the virtual file system of the document. Use the FileSystem service to view its contents, as well as to create, open and read files stored in it.

Refer to this help page to learn more on how to access and manipulate folders and files in the virtual file system of a LibreOfficeDev file.

ImportFilters

Ja

String array

Returnerer en liste med importfilternavnene som gjelder for gjeldende dokument, som en nullbasert rekke strenger. Filtre brukt for bÄde import/eksport returneres ogsÄ.

IsBase
IsCalc
IsDraw
IsFormDocument
IsImpress
IsMath
IsWriter

Ja

Boolean

NÞyaktig én av disse egenskapene er Sann for et gitt dokument.

Keywords (*)

Nei

String

Gir tilgang til nĂžkkelord-egenskapen til dokumentet. Representert som en kommadseparert liste over sĂžkeord

Readonly (*)

Ja

Boolean

True hvis dokumentet faktisk er i skrivebeskyttet modus

Subject (*)

Nei

String

Gir tilgang til emneegenskapen til dokumentet.

Title (*)

Nei

String

Gir tilgang til Tittel-egenskapen til 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

Eksemplet nedenfor skriver ut alle egenskapene til et dokument. Merk at oDoc-objektet returnert av UI.OpenDocument-metoden 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 Ä fÄ tilgang til dokumentegenskaper i et Python-skript mÄ brukeren ha direkte tilgang til dem ved Ä bruke navnene deres, som vist nedenfor:


    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 dokumenttjenesten

Activate
CloseDocument
CreateMenu
Echo

ExportAsPDF
PrintOut
RemoveMenu
RunCommand

Save
SaveAs
SaveCopyAs
SetPrinter


Activate

Returnerer True hvis dokumentet kunne aktiveres. Ellers er det ingen endring i det faktiske brukergrensesnittet. Det tilsvarer Aktiver-metoden for UI-tjenesten.

Denne metoden er nyttig nÄr man trenger Ä gi fokus for et dokument som er minimert eller skjult.

Syntaks:

svc.Activate(): bool

Eksempel:

Eksemplet nedenfor anser at filen "My_File.ods" allerede er Äpen, 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 at du kan pÄkalle Dokument-tjenesten ved Ä sende til CreateScriptService enten "Document" eller "SFDocuments.Document"


CloseDocument

Lukker dokumentet. Hvis dokumentet allerede er lukket, uavhengig av hvordan dokumentet ble lukket, har denne metoden ingen effekt og returnerer Usann.

Metoden vil ogsÄ returnere Usann hvis brukeren nekter Ä lukke den.

Returnerer Sann hvis dokumentet ble lukket.

Syntaks:

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

Parametre:

saveask : Hvis Sann (standard), inviteres brukeren til Ä bekrefte om endringene skal skrives pÄ disk. Dette argumentet ignoreres hvis dokumentet ikke ble endret.

Eksempel:

I Basic

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

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

CreateMenu

Oppretter en ny menyoppfĂžring i menylinjen i et gitt dokumentvindu.

Denne metoden returnerer en forekomst av SFWidgets.Menu-tjenesten.

note

Menyen som er opprettet er kun tilgjengelig under den gjeldende LibreOfficeDev-Þkten og lagres verken i dokumentet eller i de globale applikasjonsinnstillingene. Derfor forsvinner menyen ved Ä lukke dokumentvinduet. Den vises fÞrst nÄr makroen som oppretter menyen kjÞres igjen.


Syntaks:

svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc

Parametre:

menyhode: ToppnivÄnavnet pÄ den nye menyen.

fÞr: Navnet (som en streng) eller posisjonen (som et heltall som starter pÄ 1) pÄ en eksisterende meny som den nye menyen skal plasseres foran. Hvis ingen verdi er definert for dette argumentet, vil menyen bli opprettet pÄ den siste posisjonen i menylinjen.

submenuchar: Skilletegnet som brukes til Ä lage menytrÊr nÄr man kaller metoder som AddItem fra Meny-tjenesten. Standardverdien er ">".

Eksempel:

I Basic

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Sett oMenu = oDoc.CreateMenu("Min meny")
    With oMenu
        ' Legg til elementer i menyen
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' Etter Ă„ ha opprettet menyen, kan tjenesteforekomsten kasseres
        .Dispose()
    End With
  
I Python

    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("Min meny")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  
tip

Se SFWidgets.Menu hjelpesiden for Ă„ lĂŠre mer om hvordan du oppretter/ fjerne menyer i LibreOfficeDev dokumentvinduer.


Echo

Suspends user interface (UI) updates during the execution of a macro. Optionally, the mouse pointer can be changed into an hourglass while UI updates are suspended.

tip

This method may provide some performance benefits for macros that perform numerous operations that require UI updates.


Syntaks:

svc.Echo(echoon: bool = True, hourglass: bool = False)

Parametre:

echoon: Specify False to suspend UI updates. The default value is True, which enables real time UI updates.

hourglass: Specify True to change the mouse pointer to an hourglass (Default = False).

note

Moving the mouse pointer after it changed to an hourglass may cause it to switch to a different pointer depending on its new background.


Eksempel:

I Basic

    ' Suspends UI updates and change mouse pointer to an hourglass
    oDoc.Echo(EchoOn := False, HourGlass := True)
    ' Other macro commands
    ' ...
    ' Restores UI updates and mouse pointer
    oDoc.Echo()
  
I Python

    doc.Echo(echoon = False, hourglass = True)
    ...
    doc.Echo()
  

ExportAsPDF

Eksporterer dokumentet direkte som en PDF-fil til det angitte stedet. Returnerer Sann hvis PDF-filen ble opprettet.

Eksportalternativene kan settes enten manuelt ved Ă„ bruke Fil - Eksporter som - Eksporter som PDF-dialogboksen eller ved Ă„ kalle metodene GetPDFExportOptions og SetPDFExportOptions fra Session-tjeneste.

Syntaks:

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

Parametre:

filnavn: Den fullstendige banen og filnavnet til PDF-en som skal opprettes. Den mÄ fÞlge SF_FileSystem.FileNaming-notasjonen.

overskriv: Angir om mÄlfilen kan overskrives (Standard = Usann). En feil vil oppstÄ hvis overskriv er satt til Usann og mÄlfilen allerede eksisterer.

sider: Streng som spesifiserer hvilke sider som skal eksporteres. Dette argumentet bruker samme notasjon som i dialogen Fil - Eksporter som - Eksporter som PDF.

passord: Angir et passord for Ä Äpne PDF-filen.

vannmerke: Tekst som skal brukes som vannmerke i PDF-filen, som vil bli tegnet pÄ hver side av den resulterende PDF-filen.

Eksempel:

I Basic

FÞlgende eksempel eksporterer gjeldende dokument som en PDF-fil, definerer et passord og overskriver mÄlfilen hvis den allerede eksisterer.


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

Kodebiten nedenfor fÄr de gjeldende PDF-eksportalternativene og bruker dem til Ä lage PDF-filen.


    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Setter til Sann alternativet for Ă„ eksportere kommentarer som PDF-notater
    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 metoden sender innholdet i dokumentet til standardskriveren eller til skriveren definert av SetPrinter-metoden.

Returnerer Sann hvis dokumentet ble skrevet ut.

Syntaks:

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

Parametre:

sider: Sidene som skal skrives ut som en streng, som i brukergrensesnittet. Eksempel: "1-4;10;15-18". Standard er alle sider.

kopier: Antall 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'):
        # ...
  

RemoveMenu

Fjerner en toppnivÄmeny fra menylinjen i et gitt dokumentvindu.

Returnerer True hvis den angitte menyen kunne fjernes. Hvis den angitte menyen ikke eksisterer, returnerer metoden Usann.

note

Denne metoden kan brukes til Ä fjerne alle menyoppfÞringer fra dokumentvinduet, inkludert standardmenyer. Ingen av disse endringene i menylinjen lagres imidlertid i dokumentet eller i applikasjonsinnstillingene. For Ä gjenopprette menylinjen til standardinnstillingene, lukk og Äpne dokumentvinduet pÄ nytt.


Syntaks:

svc.RemoveMenu(menuheader: str): bool

Parametre:

menyhode: ToppnivÄnavnet pÄ menyen som skal fjernes.

Eksempel:

I Basic

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu ("Min meny")
  
I Python

    doc = CreateScriptService("Document")
    doc.RemoveMenu("Min meny")
  
tip

Se SFWidgets.Menu hjelpesiden for Ă„ lĂŠre mer om hvordan du oppretter/ fjerne menyer i LibreOfficeDev dokumentvinduer.


RunCommand

KjÞrer en UNO-kommando pÄ dokumentvinduet som er knyttet til tjenesteforekomsten. Noen typiske kommandoer er: Lagre, Lagre Som, ExportToPDF, Angre, Kopier, Lim inn, etc.

Selve dokumentet trenger ikke vĂŠre aktivt for Ă„ kunne kjĂžre kommandoer.

Kommandoer kan kjĂžres med eller uten argumenter. Argumenter blir ikke validert fĂžr kommandoen kjĂžres. Hvis kommandoen eller dens argumenter er ugyldige, vil ingenting skje.

tip

For en fullstendig liste over UNO-kommandoer som kan kjĂžres i LibreOfficeDev, se Wiki-siden Development/DispatchCommands.


Syntaks:

svc.RunCommand(command: str, [args: any])

Parametre:

kommando: Skrevet av store og smÄ bokstaver som inneholder UNO-kommandonavnet. Inkludering av prefikset ".uno:" i kommandoen er valgfritt. Selve kommandoen kontrolleres ikke for korrekthet. Hvis ingenting skjer etter kommandoanropet, er kommandoen sannsynligvis feil.

args: For hvert argument som skal sendes til kommandoen, spesifiser et par som inneholder argumentnavnet og verdien.

Eksempel:

I Basic

FÞlgende eksempel kjÞrer kommandoen SelectData i en Calc-fil kalt "MyFile.ods", som vil resultere i valg av dataomrÄdet basert pÄ den valgte cellen. Merk at denne kommandoen ikke krever noen argumenter.


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

Nedenfor er et eksempel som kjþrer UNO-kommandoen ReplaceAll og sender verdier for argumentene SearchString og ReplaceString. Å kjþre denne kommandoen vil erstatte all forekomst av strengen "abc" med "ABC" i gjeldende ark.


    ' Argumenter sendt til kommandoen:
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Merk at Ä kalle kommandoen ReplaceAll uten argumenter vil Äpne Finn og erstatt-dialogen.

I Python

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

    doc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

I Python er det ogsÄ mulig Ä kalle RunCommand ved Ä bruke sÞkeordargumenter:


    doc.RunCommand(".uno:ReplaceAll", SearchString = "abc", ReplaceString = "ABC")
  
tip

Hver LibreOfficeDev-komponent har sitt eget sett med kommandoer tilgjengelig. En enkel mÄte Ä lÊre kommandoer pÄ er Ä gÄ til VerktÞy - Tilpass - Tastatur. NÄr du plasserer musen over en funksjon i Funksjon-listen, vises et verktÞytips med den tilsvarende UNO-kommandoen.


Save

Lagrer dokumentet pÄ filplasseringen det ble lastet fra. Metoden ignoreres hvis dokumentet ikke ble endret.

Returnerer False hvis dokumentet ikke kunne lagres. En feil oppstÄr hvis filen er Äpen som skrivebeskyttet, eller hvis det er en ny fil som ikke er lagret ennÄ.

Selve dokumentet trenger ikke vĂŠre aktivt for Ă„ kjĂžre denne metoden.

Syntaks:

svc.Save(): bool

Eksempel:

I Basic

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

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

SaveAs

Lagrer dokumentet til den gitte filplasseringen. Den nye plasseringen blir det nye filnavnet som enkle Lagre-metodekall vil bli brukt pÄ.

Returnerer False hvis dokumentet ikke kunne lagres. En feil oppstÄr nÄr overskriving av destinasjonen avvises eller nÄr destinasjonen har sitt skrivebeskyttede attributt satt.

Selve dokumentet trenger ikke vĂŠre aktivt for Ă„ kjĂžre denne metoden.

Syntaks:

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

Parametre:

filnavn: En streng som inneholder filnavnet som skal brukes. Den mÄ fÞlge SF_FileSystem.FileNaming-notasjonen.

overskriv: Hvis Sann, kan mÄlfilen bli overskrevet (standard = Usann).

passord (*): En streng uten mellomrom for Ă„ beskytte dokumentet.

filternavn (*): Navnet pÄ et filter som skal brukes for Ä lagre dokumentet. Hvis dette argumentet passeres, mÄ filteret eksistere.

filteralternativer (*): En valgfri streng med alternativer knyttet til filteret.

Eksempel:

I Basic

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

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

SaveCopyAs

Lagrer en kopi av eller eksporter dokumentet til den gitte filplasseringen. Den faktiske plasseringen er uendret.

Returnerer Usann hvis dokumentet ikke kunne lagres. En feil oppstÄr nÄr overskriving av destinasjonen avvises eller nÄr destinasjonen har sitt skrivebeskyttede attributt satt.

Selve dokumentet trenger ikke vĂŠre aktivt for Ă„ kjĂžre denne metoden.

Syntaks:

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

Parametre:

filnavn: En streng som inneholder filnavnet som skal brukes. Den mÄ fÞlge SF_FileSystem.FileNaming-notasjonen.

overskriv: Hvis Sann, kan mÄlfilen bli overskrevet (standard = Usann).

passord (*): En streng uten mellomrom for Ă„ beskytte dokumentet.

filternavn (*): Navnet pÄ et filter som skal brukes for Ä lagre dokumentet. Hvis dette argumentet passeres, mÄ filteret eksistere.

filteralternativer (*): En valgfri streng med alternativer knyttet til 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 skriveralternativene for dokumentet.

Returnerer Sann nÄr det lykkes.

Syntaks:

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

Parametre:

skriver: Navnet pÄ skriverkÞen der den skal skrives ut. NÄr den er fravÊrende, angis standardskriveren.

orientering: Enten PORTRETT eller LANDSKAP. NÄr fravÊrende, forblir uendret med hensyn til skriverinnstillingene.

papirformat: Spesifiserer papirformatet som en strengverdi som kan vĂŠre enten A3, A4, A5, LETTER, LEGAL eller TABLOID. Blir uendret hvis ikke spesifisert.

Eksempel:

I Basic

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

    doc.SetPrinter(paperformat='TABLOID')
  
warning

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment Ă„ brukes i grunnleggende makroer eller Python-skript.