SFDocuments.Dokument tjeneste

SFDocuments-biblioteket gir metoder og egenskaper for å forenkle administrasjon og manipulering av LibreOffice-dokumenter.

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

• Åpne, lukke og lagre dokumenter

• Tilgang til standard eller egendefinerte egenskaper for dokumenter

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

Metoder og egenskaper som er spesifikke for visse LibreOffice-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:

• 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.

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
  

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

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

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

Egenskaper

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

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

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.

svc.Activate(): bool

Eksemplet nedenfor anser at filen "My_File.ods" allerede er åpen, men ikke aktiv.

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

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

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.

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

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

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

    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.

Menyen som er opprettet er kun tilgjengelig under den gjeldende LibreOffice-ø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.

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

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 ">".

    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
  

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

Se SFWidgets.Menu hjelpesiden for å lære mer om hvordan du oppretter/ fjerne menyer i LibreOffice dokumentvinduer.

DeleteStyles

Suppresses a single style or an array of styles given by their names within a specific styles family. Only user-defined styles may be deleted, built-in styles are ignored. It applies to all document types except Base and FormDocument.

svc.DeleteStyles(family: str, stylelist: str[1..*])

family: One of the style families present in the actual document, as a case-sensitive string. Valid family names can be retrieved using StyleFamilies property.

stylelist: A single style name as a string or an array of style names. The style names may be localized or not. The StylesList is typically the output of the execution of a Styles() method.

    ' Removing unused paragraph styles
    Const family = "ParagraphStyles"
    aList = oDoc.Styles(family, used := False, userDefined := True)
    oDoc.DeleteStyles(family, aList)
  

    # Removing styles according to a prefix
    a_list = doc.Styles('ParagraphStyles', namepattern = "Py*")
    doc.Styles('ParagraphStyles', a_list)
  

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.

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

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

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

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

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

    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.

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

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.

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

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

ImportStylesFromFile

This method loads all the styles belonging to one or more style families from a closed file into the actual document. The actual document must be a Calc or a Writer document.

Are always imported together:

• ParagraphStyles and CharacterStyles

• NumberingStyles and ListStyles

Returns True if styles were successfully imported.

svc.ImportStylesFromFile(filename: str, families: str[1..*], overwrite = False): bool

filename: The file from which to load the styles in the FileSystem notation. The file is presumed to be of the same document type as the actual document.

families: One of the style families present in the actual document, as a case-sensitive string or an array of such strings. Default = all families.

overwrite: When True, the actual styles may be overwritten. Default is False.

    oDoc.ImportStylesFromFile("C:\User\Documents\myFile.ods", "ParagraphStyles", True)
  

    doc.ImportStylesFromFile('C:\User\Documents\myFile.ods', ("ParagraphStyles",), False)
  

PrintOut

Denne metoden sender innholdet i dokumentet til standardskriveren eller til skriveren definert av SetPrinter-metoden.

Returnerer Sann hvis dokumentet ble skrevet ut.

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

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.

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

    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.

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.

svc.RemoveMenu(menuheader: str): bool

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

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

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

Se SFWidgets.Menu hjelpesiden for å lære mer om hvordan du oppretter/ fjerne menyer i LibreOffice 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.

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

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

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.

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.

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

Hver LibreOffice-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.

svc.Save(): bool

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

    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.

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

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.

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

    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.

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

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.

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

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

SetPrinter

Definerer skriveralternativene for dokumentet.

Returnerer Sann når det lykkes.

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

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.

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  

    doc.SetPrinter(paperformat='TABLOID')
  

Styles

Retrieves a list of styles matching an optional compound criteria, the returned array may be empty. It applies to all document types except Base.

svc.Styles(family, opt namepattern: str, opt used: bool, opt userdefined: bool, opt parentstyle: str, opt category: str): str[0..*])

category: A case-insensitive string: TEXT, CHAPTER, LIST, INDEX, EXTRA, HTML. For their respective meanings, refer to paragraph style category API documentation.

This argument is ignored when the Family differs from "ParagraphStyles".

namepattern: A filter on the style names, as a case-sensitive string pattern. The names include the internal and localized names.

Admitted wildcard are:

• the "?" representing any single character.

• the "*" representing zero, one, or multiple characters

parentstyle: When present, only the children of the given, localized or not, parent style name are retained.

used: When True, the style must be used in the document, when absent the argument is ignored.

userdefined: When True, the style must have been added by the user, either in the document or its template, when absent, the argument is ignored.

    Dim vStyles As Variant
    vStyles = oDoc.Styles("ParagraphStyles") 'All styles in the family
    vStyles = oDoc.Styles("ParagraphStyles", "H*") 'Heading, Heading 1, ...
    vStyles = oDoc.Styles("ParagraphStyles", Used := False, UserDefined := True) ' All user-defined styles that are not used
    vStyles = oDoc.Styles("ParagraphStyles", ParentStyle := "Standard") ' All styles derived from the 'Default Paragraph Style'
  

    vStyles = doc.Styles('ParagraphStyles')  #All styles in the family
    vStyles = doc.Styles('ParagraphStyles', 'H*')  #Heading, Heading 1, ...
    vStyles = doc.Styles('ParagraphStyles', Used = False, UserDefined = True)  # All user-defined styles that are not used
    vStyles = doc.Styles('ParagraphStyles', ParentStyle = 'Standard")  # All styles derived from the "Default Paragraph Style"
  

Toolbars

This method returns either a list of the available toolbar names in the actual document or an instance SFWidgets.Toolbar service.

svc.Toolbars(opt ToolbarName: str): uno
svc.Toolbars(): str[0..]

ToolbarName: The usual name of one of the available toolbars.

    Dim oToolbar As Object
    Set oToolbar = oDoc.Toolbars("myToolbar")
  

    a_list = doc.Toolbars()
  

XStyles

This method returns the UNO representation of a given style for all document types except Base. Nothing is returned when the StyleName does not exist in the given Family.

svc.XStyles(family: str, stylename: str): uno

stylename: One of the styles present in the given family, as a case-sensitive string. The StyleName may be localized or not.

    Dim oStyle As Object
    Set oStyle = oDoc.XStyle("ParagraphStyle", "Heading 2")
  

    oStyle = doc.XStyle('ParagraphStyle', 'Heading 2')
  

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.