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

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

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

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

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:".

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

Služba ScriptForge.Dictionary