Obsah
Rejstřík 🔎︎

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

- Otevírání, zavírání a ukládání dokumentů

- Přístup ke standardním nebo vlastním vlastnostem dokumentů

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

• 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")

Pomocí názvu okna, pokud je dokument již otevřen.

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

Pomocí dokumentu, na který odkazuje objekt ThisComponent. To je užitečné zejména při spouštění maker z prostředí Basic IDE.

        Dim oDoc As Object
        Set oDoc = CreateScriptService("Document", ThisComponent)

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

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

        bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)

        def RunEvent(event)
            doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
            # (...)

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

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.

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

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.

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

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.

Ú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")

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

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.

Související témata

Služba ScriptForge.Dictionary

Služba ScriptForge.UI

Služba SFWidgets.Menu