Storitev SFDocuments.Document

Knjižnica SFDocuments vsebuje metode in lastnosti, ki lajšajo upravljanje in ravnanje z dokumenti LibreOffice.

Metode, ki veljajo za vse vrste dokumentov (besedilne dokumente, preglednice, predstavitve itn.) so vključene v storitev SFDocuments.Document. Nekaj primerov:

warning

Lastnosti, metode in argumenti, označeni z zvezdico (*) NE veljajo za dokumente Base.


Metode in lastnosti, specifične za določen modul LibreOffice, se hranijo v ločenih storitvah, kot sta SFDocuments.SF_Calc in SFDocuments.SF_Base.

Čeprav jezik Basic ne ponuja dedovanja med razredi predmetov, lahko slednje storitve štejemo za podrazrede storitve SFDocuments.Document. Takšni podrazredi lahko prikličejo lastnosti in metode, ki so opisani v nadaljevanju.

Priklic storitve

Spodaj so trije načini, kako lahko prikličete storitev Document.

V Basicu

Z uporabo metode getDocument iz storitve ScriptForge.UI:


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

Namesto tega lahko uporabite metodi CreateDocument in OpenDocument iz storitve UI.


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

Neposredno, če je dokument že odprt.


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

Iz makra, ki ga proži dogodek dokumenta.


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

Storitev Document je tesno povezana s storitvama UI in FileSystem.


Če dokumenta ni zaprl program z metodo CloseDocument (sicer je ta napotek odveč), priporočamo, da po uporabi sprostite vire:


    Set oDoc = oDoc.Dispose()
  
V Pythonu

    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

Uporaba predpone "SFDocuments." pri klicu storitve je neobvezna.


Lastnosti

Ime

Samo za branje

Vrsta

Opis

CustomProperties (*)

Ne

Dictionary service

Vrne instanco predmeta ScriptForge.Dictionary. Po posodobitvi ga lahko znova podate lastnosti za posodobitev dokumenta.
Posamezni elementi slovarja so lahko nizi, števila, datumi (Basic) ali elementi com.sun.star.util.Duration.

Description (*)

Ne

String

Nudi dostop do opisa dokumenta (lastnost Description), znano tudi pod nazivom Komentarji (angl. "Comments")

DocumentProperties (*)

Da

Dictionary service

Vrne predmet ScriptForge.Dictionary, ki vsebuje vse vnose. Statistika dokumenta je vključena. Upoštevajte, da se glede na vrsto dokumentov razlikuje. Primer: dokument programa Calc vsebuje vnos "CellCount", torej števec celic. Druge vrste dokumentov tega vnosa nimajo.

DocumentType

Da

String

Vrednost niza z vrsto dokumenta ("Base", "Calc", "Writer" itn.)

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

Da

Boolean

Natanko ena od teh lastnosti je enaka True za dani dokument.

Keywords (*)

Ne

String

Nudi dostop do ključnih besed dokumenta (lastnost Keywords). Predstavljen v obliki z vejicami ločenega seznama ključnih besed

Readonly (*)

Da

Boolean

True, če je dokument dejansko v načinu samo za branje

Subject (*)

Ne

String

Nudi dostop do zadeve dokumenta (lastnost Subject).

Title (*)

Ne

String

Nudi dostop do naslova dokumenta (lastnost Title).

XComponent

Da

Predmet UNO

Predmet UNO com.sun.star.lang.XComponent ali com.sun.star.comp.dba.ODatabaseDocument, ki predstavlja dokument


Primer:

V Basicu

Spodnji primer izpiše vse lastnosti dokumenta. Upoštevajte, da je predmet oDoc, ki ga vrne metoda UI.OpenDocument, predmet SFDocuments.Document.


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

Če želite dostopati do lastnosti dokumenta v skriptu Python, morate neposredno dostopati z rabo njihovih imen, kot je prikazano spodaj:


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

Seznam metod storitve Document

Activate
CloseDocument
Forms

RunCommand
Save

SaveAs
SaveCopyAs


Activate

Vrne True, če je aktivacija dokumenta uspela. Sicer v dejanskem uporabniškem vmesniku ni sprememb. Je enakovredna metodi Activate storitve UI.

Ta metoda je uporabna, ko želite pozornost usmeriti na dokument, ki je pomanjšan ali skrit.

Skladnja:

svc.Activate(): bool

Primer:

Spodnji primer predvideva, da je datoteka "My_File.ods" že odprta, vendar ni aktivna.

V Basicu

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

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

Upoštevajte, da lahko prikličete storitev Document s podajanjem "Document" ali "SFDocuments.Documentby" k CreateScriptService.


CloseDocument

Zapre dokument. Če je dokument že zaprt (ne glede na to, kako je bil zaprt), ta metoda nima učinka in vrne False.

Ta metoda vrne False, če uporabnik zavrne njeno zaprtje.

Vrne True, če je bil dokument uspešno zaprt.

Skladnja:

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

Parametri:

saveask: če je enako True (privzeto), povpraša uporabnika, da potrdi, ali naj se spremembe shranijo na disk. Ta argument je prezrt, če dokument ni bil spremenjen.

Primer:

V Basicu

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

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

Forms

Glede na podane parametre ta metoda vrne:

note

Ta metoda velja le za dokumente programa Writer. Dokumenti programov Calc in Base imajo lastno metodo Forms v svojih storitvah Calc in Base.


Skladnja:

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

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

svc.Forms(form: int): svc

Parametri:

form: ime ali številka indeksa obrazca, shranjenega v dokumentu. Če ta argument ni podan, metoda vrne seznam z imeni vseh obrazcev, ki so na voljo v dokumentu.

Primer:

V naslednjih primerih prva vrstica pridobi imena vseh obrazcev v dokumentu, druga pa predmet Form obrazca z imenom »Obrazec_A«.

V Basicu

    Set FormNames = oDoc.Forms()
    Set FormA = oDoc.Forms("Obrazec_A")
  
V Pythonu

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

RunCommand

Izvede ukaz nad dokumentom. Ukaz se izvede brez argumentov.

Nekaj tipičnih ukazov: Save (Shrani), SaveAs (Shrani kot), ExportToPDF (IzvoziVPDF), SetDocumentProperties (Določi lastnosti dokumenta), Undo (Razveljavi), Copy (Kopiraj), Paste (Prilepi) itn.

Sam dokument ne rabi biti aktiven, da bi lahko izvedli ukaze.

Skladnja:

svc.RunCommand(command: str)

Parametri:

command: niz, ki vsebuje ukaz v angleškem jeziku (razlikuje med velikimi in malimi črkami). Sama pravilnost ukaza se ne preverja. Če se po klicu ukaza ne zgodi nič, je z ukazom oz. njegovim klicem najbrž nekaj narobe.

Primer:

Naslednji primer izvede ukaz SelectData na delovnem listu preglednice programa Calc z imenom MyFile.ods, ki vrne izbor območja podatkov glede na položaj trenutno izbrane celice.

V Basicu

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

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

Zgornji primer dejansko izvede ukaz UNO uno:SelectData. Zato je potrebno za uporabo metode RunCommand odstraniti podniz "uno:".

tip

Vsak program paketa LibreOffice ima lasten nabor ukazov, ki so na voljo. Enostaven način spoznavanja takšnih ukazov je priklic okna Orodja > Prilagodi > Tipkovnica. Ko postavite miško nad funkcijo na seznamu Funkcija, se pojavi namig z ustreznim ukazom UNO.


Save

Shrani dokument na datotečno mesto, s katerega je bil naložen. Metoda je prezrta, če dokument ni bil spremenjen.

Vrne False, če je shranjevanje dokumenta spodletelo. Če je datoteka odprta samo za branje ali če gre za novo datoteko, ki še ni bila shranjena, prikliče napako.

Sam dokument ne rabi biti aktiven, da bi lahko izvedli to metodo.

Skladnja:

svc.Save(): bool

Primer:

V Basicu

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

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

SaveAs

Shrani dokument na podano datotečno mesto. Novo mesto postane novo ime datoteke, nad katerim bodo uveljavljeni enostavni klici metode Save (Shrani).

Vrne False, če je shranjevanje dokumenta spodletelo. Prikliče napako, če je prepis cilja zavrnjen ali če ima cilj določen atribut samo za branje.

Sam dokument ne rabi biti aktiven, da bi lahko izvedli to metodo.

Skladnja:

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

Parametri:

filename: niz, ki vsebuje ime datoteke, ki ga želite uporabiti. Slediti mora zapisu SF_FileSystem.FileNaming.

overwrite: če je True, je ciljno datoteko možno prepisati (privzeto = False).

password (*): niz brez presledkov za geslo, s katerim zaščitite dokument.

filtername (*): ime filtra, ki naj bo uporabljen za shranjevanje dokumenta. Če ta argument podate, mora filter obstajati.

filteroptions (*): neobvezen niz možnosti, povezanih s filtrom.

Primer:

V Basicu

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

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

SaveCopyAs

Shrani kopijo ali izvoženi dokument na podano mesto shranjevanja. Dejansko mesto hrambe ostane nespremenjeno.

Vrne False, če je shranjevanje dokumenta spodletelo. Prikliče napako, če je prepis cilja zavrnjen ali če ima cilj določen atribut samo za branje.

Sam dokument ne rabi biti aktiven, da bi lahko izvedli to metodo.

Skladnja:

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

Parametri:

filename: niz, ki vsebuje ime datoteke, ki ga želite uporabiti. Slediti mora zapisu SF_FileSystem.FileNaming.

overwrite: če je True, je ciljno datoteko možno prepisati (privzeto = False).

password (*): niz brez presledkov za geslo, s katerim zaščitite dokument.

filtername (*): ime filtra, ki naj bo uporabljen za shranjevanje dokumenta. Če ta argument podate, mora filter obstajati.

filteroptions (*): neobvezen niz možnosti, povezanih s filtrom.

Primer:

V Basicu

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

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

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic niso namenjeni.


Podprite nas!