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

Před používáním služby Document je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

note

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService


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

ExportFilters

ano

String array

Vrátí seznam názvů exportních filtrů použitelných pro aktuální dokument, a to jako pole řetězců začínající od 0. Vrátí se také filtry používané zároveň pro import i export.

ImportFilters

ano

String array

Vrátí seznam názvů importních filtrů použitelných pro aktuální dokument, a to jako pole řetězců začínající od 0. Vrátí se také filtry používané zároveň pro import i export.

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
CreateMenu
ExportAsPDF

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

CreateMenu

Vytvoří novou položku v hlavní nabídce daného okna s dokumentem.

Tato metoda vrátí instanci služby SFWidgets.Menu.

note

Vytvořená nabídka je k dispozici pouze po dobu trvání aktuální relace LibreOffice a není uložena v dokumentu ani v globálním nastavení aplikace, tudíž po zavření dokumentu nabídka zmizí. Znovu se zobrazí pouze po spuštění makra, jež ji vytváří.


Syntaxe:

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

Parametry:

menuheader: Název nejvyšší úrovně nové nabídky.

before: Název (řetězec) nebo pozice (celé číslo začínající od jedné) existující nabídky, před niž bude nová nabídka umístěna. Pokud není tomuto argumentu určena hodnota, nabídka bude vytvořena na konci hlavní nabídky.

submenuchar: Oddělovač použitý k vytváření hierarchie nabídek při volání metod, jako je AddItem ze služby Menu. Výchozí hodnota je ">".

Příklad:

V Basicu

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Set oMenu = oDoc.CreateMenu("Moje nabídka")
    With oMenu
        ' Přidá položky do nabídky
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' Po vytvoření nabídky je možné instanci služby uvolnit
        .Dispose()
    End With
  
V Pythonu

    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("Moje nabídka")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  
tip

Další informace o vytváření a odstraňování nabídek v oknech LibreOffice s dokumenty naleznete na stránce o službě SFWidgets.Menu.


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

RemoveMenu

Odstraní nabídku nejvyšší úrovně z hlavní nabídky daného okna s dokumentem.

Vrátí True, pokud je možné určenou nabídku odstranit. Pokud tato nabídka neexistuje, metoda vrátí False.

note

Tato metoda může být použita k odstranění jakékoliv položky nabídky v okně s dokumentem, včetně výchozích nabídek. Žádná z těchto změn však není uložena do dokumentu ani do nastavení aplikace. Hlavní nabídku obnovíte do výchozího nastavení prostým zavřením a znovuotevřením okna s dokumentem.


Syntaxe:

svc.RemoveMenu(menuheader: str): bool

Parametry:

menuheader: Název nejvyšší úrovně nabídky, která se má odstranit.

Příklad:

V Basicu

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu("Moje nabídka")
  
V Pythonu

    doc = CreateScriptService("Document")
    doc.RemoveMenu("Moje nabídka")
  
tip

Další informace o vytváření a odstraňování nabídek v oknech LibreOffice s dokumenty naleznete na stránce o službě SFWidgets.Menu.


RunCommand

Spustí příkaz UNO na okno dokumentu přiřazené k instanci služby. Typickými příkazy jsou: Save, SaveAs, ExportToPDF, Undo, Copy, Paste atd.

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

Příkazy lze spouštět s argumenty nebo bez nich. Přes spuštěním příkazu se argumenty nekontrolují. Pokud je příkaz nebo jeho argumenty neplatné, nic se neprovede.

tip

Úplný seznam příkazů UNO, které lez v LibreOffice spouštět, naleznete na wiki stránce Development/DispatchCommands.


Syntaxe:

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

Parametry:

command: Řetězec, u něhož se rozlišuje velikost písmen, obsahující název příkazu UNO. Předpona ".uno:" je v názvu příkazu nepovinná. Nekontroluje se správnost příkazu. Jestliže se po zavolá příkazu nic nestane, je pravděpodobně chybný.

args: Pro každý argument, který se má příkazu předat, určete dvojici udávající název a hodnotu argumentu.

Příklad:

V Basicu

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


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

V níže uvedeném příkladu se spustí příkaz UNO ReplaceAll a předají se mu hodnoty argumentů SearchString a ReplaceString. Spuštěním tohoto příkazu budou na aktuálním listu nahrazeny všechny výskyty řetězce "abc" řetězcem "ABC".


    ' Argumenty předané příkazu:
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Volání příkazu ReplaceAll bez argumentů otevře dialogové okno Najít a nahradit.

V Pythonu

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

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

V Pythonu je možné při volání metody RunCommand použít názvy argumentů:


    doc.RunCommand(".uno:ReplaceAll", SearchString = "abc", ReplaceString = "ABC")
  
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.


Podpořte nás!