Innhald
Innhaldsliste 🔎︎

# Tenesta SFDocuments.Document

The SFDocuments library provides methods and properties to facilitate the management and manipulation of LibreOffice documents.

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.

Methods and properties that are specific to certain LibreOffice components are stored in separate services, such as SFDocuments.SF_Calc and 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

Before using the Document service the ScriptForge library needs to be loaded or imported:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

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)
ExportFilters | Yes | String array | Returns a list with the export filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned.
ImportFilters | Yes | String array | Returns a list with the import filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned.
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 CreateMenu ExportAsPDF | PrintOut RemoveMenu 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):
            # ...

## CreateMenu

Creates a new menu entry in the menubar of a given document window.

This method returns an instance of the SFWidgets.Menu service.

The menu created is only available during the current LibreOffice session and is not saved neither in the document nor in the global application settings. Hence closing the document window will make the menu disappear. It will only reappear when the macro that creates the menu is executed again.

### Syntaks:

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

### Parametrar:

menuheader: The toplevel name of the new menu.

before: The name (as a string) or position (as an integer starting at 1) of an existing menu before which the new menu will be placed. If no value is defined for this argument, the menu will be created at the last position in the menubar.

submenuchar: The delimiter used to create menu trees when calling methods as AddItem from the Menu service. The default value is ">".

### Eksempel:

##### I Basic

        Dim oDoc as Object, oMenu as Object
        Set oDoc = CreateScriptService("Document")
        Set oMenu = oDoc.CreateMenu("My Menu")
        With oMenu
            ' Add items to the menu
            .AddItem("Item A")
            .AddItem("Item B")
            ' ...
            ' After creating the menu, the service instance can be disposed of
            .Dispose()
        End With

##### I Python

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

Refer to the SFWidgets.Menu help page to learn more about how to create/remove menus in LibreOffice document windows.

## ExportAsPDF

Eksporterer dokumentet direkte som ei PDF-fil til den gjevne plasseringa. Returnerer Sann viss PDF-fila vart laga.

Innstillingane for eksport kan setjast anten manuelt med dialogvindauget Fil → Eksporter som → Eksporter som PDF eller ved å kalla opp metodane GetPDFExportOptions og SetPDFExportOptions frå tenesta Session.

### Syntaks:

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

### Parametrar:

filnamn: Den fullstendige stien og filnamnet på PDF-fila som skal lagast. Det må følgja notasjonen i SF_FileSystem.FileNaming.

overskriv: Spesifiserer om målcella kan overskrivast (Standard = Usann). Det kjem opp ei feilmelding viss overwrite er sett til Usann og målfila finst frå før.

sider: Streng som spesifiserer kva for sider som skal eksporterast. Dette argument brukar den same notasjonen som i dialogvindauget Filer → Eksporter som → Eksporter som PDF.

password: Spesifiserer eit passord for å opna PDF-fila.

vassmerke: Tekst som skal brukast som vassmerke i PDF-fila og som vert sett inn på kvar side i PDF-dokumentet.

### Eksempel:

##### I Basic

Eksempelet nedanfor eksporterer det gjeldande dokumentet som ei PDF-fil, definerer eit passord og overskriv målfila viss denne finst frå før.

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

Kodesnutten nedanfor hentar dei gjeldande innstillingane for eksport av PDF og brukar desse for å laga PDF-fila.

        Dim exportSettings as Object, oSession as Object
        oSession = CreateScriptService("Session")
        exportSettings = oSession.GetPDFExportOptions()
        ' Set innstillinga for eksport av merknadar som PDF-notat til Sann.
        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 innhaldet i dokument til standardskrivaren eller til den skrivaren som er definert med metoden SetPrinter.

Returnerer Sann viss utskrivinga av dokumentet lukkast.

### Syntaks:

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

### Parametrar:

sider: Sidene som skal skrivast ut som ein streng, som i brukargrensesnittet. Eksempel: «1-4;10;15-18». Standard er alle sidene.

kopiar: Talet på kopiar. 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

Removes a toplevel menu from the menubar of a given document window.

Returns True if the specified menu could be removed. If the specified menu does not exist, the method returns False.

This method can be used to remove any menu entry from the document window, including default menus. However, none of these changes in the menubar are saved to the document or to the application settings. To restore the menubar to the default settings, simply close and reopen the document window.

### Syntaks:

svc.RemoveMenu(menuheader: str): bool

### Parametrar:

menuheader: The toplevel name of the menu to be removed.

### Eksempel:

##### I Basic

        Dim oDoc as Object
        Set oDoc = CreateScriptService("Document")
        oDoc.RemoveMenu("My Menu")

##### I Python

        doc = CreateScriptService("Document")
        doc.RemoveMenu("My Menu")

Refer to the SFWidgets.Menu help page to learn more about how to create/remove menus in LibreOffice document windows.

## RunCommand

Runs a UNO command on the document window associated with the service instance. A few typical commands are: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

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

Commands can be run with or without arguments. Arguments are not validated before running the command. If the command or its arguments are invalid, then nothing will happen.

For a complete list of UNO commands that can be run in LibreOffice, refer to the Wiki page Development/DispatchCommands.

### Syntaks:

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

### Parametrar:

command: Case-sensitive string containing the UNO command name. The inclusion of the prefix ".uno:" in the command is optional. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.

args: For each argument to be passed to the command, specify a pair containing the argument name and value.

### Eksempel:

##### I Basic

The following example runs the SelectData command in a Calc file named "MyFile.ods", which will result in the selection of the data area based on the currently selected cell. Note that this command does not require any arguments.

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

Below is an example that runs the UNO command ReplaceAll and passes values for its arguments SearchString and ReplaceString. Running this command will replace all occurrence of the string "abc" by "ABC" in the current sheet.

        ' Arguments passed to the command:
        ' SearchString  = "abc"
        ' ReplaceString = "ABC"
        oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")

Note that calling the command ReplaceAll without arguments will open the Find and Replace dialog.

##### I Python

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

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

In Python it is also possible to call RunCommand using keyword arguments:

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

Each LibreOffice component has its own set of commands available. One easy way to learn commands is going to Tools - Customize - Keyboard. When you position your mouse over a function in the Function list, a tooltip will appear with the corresponding UNO command.

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

Definerer innstillingane for utskriving av dokument.

Returnerer Sann når han lukkast.

### Syntaks:

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

### Parametrar:

printer: Namnet på utskriftskøen det skal skrivast til. Når denne manglar, vert standardskrivaren sett.

papirretning: Anten PORTRAIT (ståande) eller LANDSCAPE (liggjande). Når denne manglar vert feltet ikkje endra i høve til skrivarinnstillingane.

papirformat: Spesifiserer papirformatet som ein strengverdi som kan vera anten A3, A4, A5, LETTER, LEGAL eller TABLOID. Vert ikkje endra om denne manglar.

### Eksempel:

##### I Basic

        oDoc.SetPrinter(Orientation := "PORTRAIT")

##### I Python

        doc.SetPrinter(paperformat='TABLOID')

Alle ScriptForge Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Liknande emne

Tenesta ScriptForge.Dictionary

Tenesta ScriptForge.UI

SFWidgets.Menu service