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

In Basic

Using the getDocument method from the ScriptForge.UI service:


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

Alternatively you can use the methods CreateDocument and OpenDocument from the UI service.


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

Directly if the document is already open.


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

From a macro triggered by a document event.


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

The Document service is closely related to the UI and FileSystem services.


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()
  
In 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 præfixet "SFDocuments." under kald af tjenesten er valgfri.


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:

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

To access document properties in a Python script the user needs to directly access them using their names, as shown below:


    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.

In Basic

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.Activate()
  
In 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:

saveask : If True (default), the user is invited to confirm if the changes should be written on disk. This argument is ignored if the document was not modified.

Eksempel:

In Basic

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

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

Forms

Depending on the parameters provided this method will return:

note

This method is applicable only for Writer documents. Calc and Base documents have their own Forms method in the Calc and Base services, respectively.


Syntaks:

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

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

svc.Forms(form: int): svc

Parametre:

form: The name or index corresponding to a form stored in the document. If this argument is absent, the method will return a list with the names of all forms available in the document.

Eksempel:

In the following examples, the first line gets the names of all forms in the document and the second line retrieves the Form object of the form named "Form_A".

In Basic

    Set FormNames = oDoc.Forms()
    Set FormA = oDoc.Forms("Form_A")
  
In 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:

command: Case-sensitive string containing the command in English. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.

Eksempel:

The following example runs the "SelectData" command in a Calc sheet named "MyFile.ods", which will result in the selection of the data area based on the currently selected cell.

In Basic

    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.RunCommand("SelectData")
  
In 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:"

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:

In Basic

    If Not oDoc.Save() Then
        ' ...
    End If
  
In 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:

filename: A string containing the file name to be used. It must follow the SF_FileSystem.FileNaming notation.

overwrite: If True, the destination file may be overwritten (default = False).

password (*): A non-space string to protect the document.

filtername (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.

filteroptions (*): An optional string of options associated with the filter.

Eksempel:

In Basic

    oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)
  
In 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:

filename: A string containing the file name to be used. It must follow the SF_FileSystem.FileNaming notation.

overwrite: If True, the destination file may be overwritten (default = False).

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

filtername (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.

filteroptions (*): An optional string of options associated with the filter.

Eksempel:

In Basic

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

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

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.


Støt os venligst!