Služba SFDocuments.Document

Knihovna SFDocuments nabízí metody a vlastnosti pro správu dokumentů LibreOffice a manipulaci s nimi.

Metody, které lze použít u všech typů dokumentů (textové dokumenty, sešity, prezentace apod.), jsou poskytovány službou SFDocuments.Document. Jedná se například o:

warning

Vlastnosti, metody či argumenty označené hvězdičkou (*) není možné použít u dokumentů aplikace Base.


Metody a vlastnosti specifické pro určitou aplikaci LibreOffice jsou uloženy v oddělených službách, například SFDocuments.SF_Calc nebo SFDocuments.SF_Base.

Ačkoliv jazyk Basic nepodporuje dědičnost mezi třídami, na tyto služby lze nahlížet jako na podtřídy služby SFDocuments.Document, které mohou volat níže popsané vlastnosti a metody.

Volání služby

Následují tři způsoby, jakými lze službu Dokument připravit.

V Basicu

Pomocí metody getDocument ze služby ScriptForge.UI:


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

Můžete také použít metody CreateDocument a OpenDocument ze služby UI.


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

Nebo přímo, pokud je dokument již otevřen.


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

Z makra spuštěného událostí dokumentu.


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

Služba Document úzce souvisí se službami UI a FileSystem.


Kromě případů, kdy byl dokument zavřen programem pomocí metody CloseDocument, se doporučuje po použití uvolnit zdroje:


    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

Použití předpony "SFDocuments." není při volání této služby povinné.


Vlastnosti

Název

Pouze pro čtení

Typ

Popis

CustomProperties (*)

ne

Dictionary service

Vrátí instanci objektu ScriptForge.Dictionary. Po úpravách ji lze předat zpět do této vlastnosti a dokument tak aktualizovat.
Jednotlivými položkami slovníku mohou být řetězce, čísla, data (jazyka Basic) neb položky typu com.sun.star.util.Duration.

Description (*)

ne

String

Poskytuje přístup k vlastnosti dokumentu Description (známé také jako „komentáře“)

DocumentProperties (*)

ano

Dictionary service

Vrátí objekt ScriptForge.Dictionary obsahující všechny záznamy včetně statistiky pro dokument. Výsledek je specifický pro jednotlivé typy dokumentu, například dokument Calcu obsahuje položku "CellCount", ostatní dokumenty nikoliv.

DocumentType

ano

String

Řetězec s typem dokumentu ("Base", "Calc", "Writer" atd.).

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

ano

Boolean

Pro daný dokument má hodnotu True právě jedna z těchto vlastností.

Keywords (*)

ne

String

Poskytuje přístup k vlastnosti dokumentu Keywords, reprezentované jako čárkami oddělený seznam klíčových slov.

Readonly (*)

ano

Boolean

True, pokud se dokument aktuálně nachází v režimu jen pro čtení.

Subject (*)

ne

String

Poskytuje přístup k vlastnosti dokumentu Subject.

Title (*)

ne

String

Poskytuje přístup k vlastnosti dokumentu Title.

XComponent

ano

objekt UNO

Objekt UNO com.sun.star.lang.XComponent nebo com.sun.star.comp.dba.ODatabaseDocument představující dokument.


Příklad:

V Basicu

Níže uvedený příklad vypíše všechny vlastnosti dokumentu. Objekt oDoc vrácený metodou UI.OpenDocument je objekt typu 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

Ve skriptech Pythonu se k vlastnostem dokumentu přistupuje přímo pomocí jejich názvů, jak je ukázáno níže:


    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 služby Document

Activate
CloseDocument
ExportAsPDF

PrintOut
RunCommand
Save

SaveAs
SaveCopyAs
SetPrinter


Activate

Vrátí True, pokud byl dokument aktivován. V opačném případě se aktuální uživatelské rozhraní nezmění. Odpovídá metodě Activate ze služby UI.

Tato metoda je užitečná v případě, kdy chcete zaměřit minimalizovaný či skrytý dokument.

Syntaxe:

svc.Activate(): bool

Příklad:

V následujícím příkladu se předpokládá, že soubor "My_File.ods" je již otevřen, ale neaktivní.

V Basicu

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

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

Mějte na paměti, že při volání služby Document můžete do metody CreateScriptService předat hodnotu "Document" i "SFDocuments.Document".


CloseDocument

Zavře dokument. Jestliže byl dokument již zavřen (bez ohledu na způsob zavření), metoda neprovede nic a vrátí False.

Metoda vrátí False i tehdy, když uživatel uzavření odmítne.

V případě úspěšného zavření dokumentu vrátí True.

Syntaxe:

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

Parametry:

saveask : Je-li True (výchozí), uživatel je vyzván k potvrzení, zda mají být změny zapsány na disk. Pokud dokument nebyl změněn, argument se ignoruje.

Příklad:

V Basicu

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

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

ExportAsPDF

Vyexportuje dokument přímo jako soubor PDF na zadané umístění. V případě úspěšného vytvoření souboru PDF vrátí True.

Možnosti exportu lze nastavit buď ručně v dialogovém okně Soubor - Exportovat jako - Exportovat jako PDF, nebo voláním metod GetPDFExportOptions a SetPDFExportOptions ze služby Session.

Syntaxe:

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

Parametry:

filename: Úplná cesta a název souboru PDF, který se má vytvořit. Musí odpovídat zápisu SF_FileSystem.FileNaming.

overwrite: Určuje, zda může být cílový soubor přepsán (výchozí = False). Je-li hodnota False a cílový soubor již existuje, nastane chyba.

pages: Řetězec určující, které stránky budou exportovány. Tento argument používá stejný zápis, jaký se používá v dialogovém okně Soubor - Exportovat jako - Exportovat jako PDF.

password: Určuje heslo pro otevření souboru PDF.

watermark: Text, který se má použít jako vodoznak, nakreslený na každé stránce výsledného souboru PDF.

Příklad:

V Basicu

V následujícím příkladu je aktuální dokument vyexportován jako soubor PDF s nastaveným heslem. Pokud cílový soubor již existuje, je přepsán.


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

V níže uvedené části kódu se získají aktuální možnosti exportu a použijí se pro vytvoření souboru PDF.


    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Nastaví na True možnost exportovat komentáře jako poznámky PDF
    exportSettings.ReplaceItem("ExportNotes", True)
    oSession.SetPDFExportOptions(exportSettings)
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")
  
V Pythonu

    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

Tato metoda odešle obsah daného dokumentu na výchozí tiskárnu nebo na tiskárnu určenou metodou SetPrinter.

Vrátí True, pokud byl dokument úspěšně vytištěn.

Syntaxe:

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

Parametry:

pages: Stránky, které se mají vytisknout, jako řetězec podobný tomu, který se zadává v uživatelské rozhraní, například: "1-4;10;15-18". Výchozí jsou všechny stránky.

copies: Počet kopií. Výchozí je 1.

Příklad:

V Basicu

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

    if doc.PrintOut(copies=3, pages='45-88'):
        # ...
  

RunCommand

Spustí na dokument příkaz, který se vykoná bez argumentů.

Typickými příkazy jsou: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste atd.

Není nutné, aby byl kvůli spouštění příkazů dokument aktivní.

Syntaxe:

svc.RunCommand(command: str)

Parametry:

command: Řetězec, u něhož se rozlišuje velikost písmen, obsahující příkaz v angličtině. Nekontroluje se správnost příkazu. Jestliže se po zavolá příkazu nic nestane, je pravděpodobně chybný.

Příklad:

V následujícím příkladu se spustí příkaz "SelectData" na list Calcu ze souboru "MyFile.ods". Výsledkem příkazu je výběr oblasti dat závisející na aktuálně vybrané buňce.

V Basicu

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

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

Ve výše uvedeném příkladu se spouští příkaz UNO .uno:SelectData. Při použití v metodě RunCommand je tedy nezbytné z názvu příkazu odstranit část řetězce obsahující ".uno:".

tip

Sada dostupných příkazů závisí na používané komponentě LibreOffice. Jednoduchým způsobem, jak příkazy zjistit, je přejít na Nástroje > Přizpůsobit > Klávesnice. Umístíte-li myš nad funkci v seznamu Funkce, zobrazí se tip s příslušným příkazem UNO.


Save

Uloží dokument na umístění, odkud byl načten. Pokud dokument nebyl změněn, metoda je ignorována.

Pokud dokument nemohl být uložen, vrátí False. Je-li soubor otevřen pouze pro čtení nebo jedná-li se o dosud neuložený nový soubor, nastane chyba.

Není nutné, aby byl kvůli spouštění této metody dokument aktivní.

Syntaxe:

svc.Save(): bool

Příklad:

V Basicu

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

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

SaveAs

Uloží dokument na zadané umístění. Nové umístění se stane novým názvem souboru, který se dále bude používat pro jednodušší metodu Save.

Pokud dokument nemohl být uložen, vrátí False. Není-li povoleno přepsání cílového umístění nebo je-li cílové umístění v režimu pouze pro čtení, nastane chyba.

Není nutné, aby byl kvůli spouštění této metody dokument aktivní.

Syntaxe:

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

Parametry:

filename: Řetězec obsahující název souboru, který se má použít. Musí odpovídat zápisu SF_FileSystem.FileNaming.

overwrite: Je-li True, cílový soubor může být přepsán (výchozí = False).

password (*): Řetězec pro uzamknutí dokumentu.

filtername (*): Název filtru, který by se měl pro uložení dokumentu použít. Je-li tento argument předán, filtr musí existovat.

filteroptions (*): Nepovinný řetězec možností pro zadaný filtr.

Příklad:

V Basicu

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

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

SaveCopyAs

Uloží kopii dokumentu nebo jej vyexportuje na zadané umístění. Aktuální umístění dokumentu se přitom nezmění.

Pokud dokument nemohl být uložen, vrátí False. Není-li povoleno přepsání cílového umístění nebo je-li cílové umístění v režimu pouze pro čtení, nastane chyba.

Není nutné, aby byl kvůli spouštění této metody dokument aktivní.

Syntaxe:

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

Parametry:

filename: Řetězec obsahující název souboru, který se má použít. Musí odpovídat zápisu SF_FileSystem.FileNaming.

overwrite: Je-li True, cílový soubor může být přepsán (výchozí = False).

password (*): Řetězec pro uzamknutí dokumentu.

filtername (*): Název filtru, který by se měl pro uložení dokumentu použít. Je-li tento argument předán, filtr musí existovat.

filteroptions (*): Nepovinný řetězec možností pro zadaný filtr.

Příklad:

V Basicu

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

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

SetPrinter

Stanoví možnosti tisku dokumentu.

Vrátí True v případě úspěšného nastavení.

Syntaxe:

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

Parametry:

printer: Název tiskové fronty, do níž se má úloha zařadit. Není-li zadán, nastaví se výchozí tiskárna.

orientation: Buď PORTRAIT (na výšku), nebo LANDSCAPE (na šířku). Není-li zadáno, ponechá se nastavení tiskárny.

paperformat: Určuje formát papíru jako řetězec, kterým může být A3, A4, A5, LETTER, LEGAL or TABLOID. Není-li zadáno, nastavení se nezmění.

Příklad:

V Basicu

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
V Pythonu

    doc.SetPrinter(paperformat='TABLOID')
  
warning

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.