Indhold
Indholdsfortegnelse 🔎︎

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

- Åbning, lukning og lagring af dokumenter

- Adgang til dokumenters standard- eller tilpassede egenskaber

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

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

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 Forms | RunCommand Save | SaveAs SaveCopyAs

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

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

## Forms

Afhængigt af de angivne parametere returnerer denne metode:

- En nul-baseret matrix (eller en tuple i Python) med navne på formularer, der er indeholdt i dokumentet (hvis argumentet form (formular) mangler)

- Et eksemplar af tjenesten SFDocuments.Form, der repræsenterer den givne formular som argument.

Denne metode er kun anvendelig på Writer dokumenter. Calc- og Base-dokuments har deres egen metode Forms (formularer) i tjenesterne henholdsvis Calc og Base.

### Syntaks:

svc.Forms(): str[0..*]

svc.Forms(form: str = ''): svc

svc.Forms(form: int): svc

### Parametre:

formular: Navnet eller indekset, der svar til en formular, der er gemt i dokumentet. Hvis dette argument mangler, returnerer metoden en liste over alle tilgængelige formularer i dokumentet.

### Eksempel:

I de følgende eksempler finder den første linje navnene på alle formularer i dokumentet og den anden linje henter objektet for Form (formular) for formularen ved navn "Formular_A".

##### I Basic

        Set FormNames = oDoc.Forms()
        Set FormA = oDoc.Forms("Form_A")

##### I Python

        form_names = doc.Forms()
        form_A = doc.Forms("Form_A")

## 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ødvendig at bruge metoden RunCommand (Kør kommando) for at fjerne delstrengen "uno:"

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)

Alle ScriptForge Basic-rutiner eller identifikatorer, som indledes med et understregningstegn "_" er reserveret til internt brug. De er ikke beregnet til brug i Basic-makroer.

Relaterede emner

Tjenesten ScriptForge.UI (brugerflade)

Tjenesten ScriptForge.Ordbog