Obsah

# Vytváření skriptů Pythonu s knihovnouScriptForge

## Rozdíly mezi jazyky Basic a Python

Knihovna Scriptforge je k dispozici pro jazyky Basic a Python. Většina služeb, metod a vlastností funguje v obou programovacích jazycích stejně. Vzhledem k odlišnostem mezi nimi si však uživatel používající ScriptForge v Pythonu musí být vědom některých charakteristik této knihovny:

- Názvy metod a vlastností: V Pythonu lze pro názvy metod a vlastností použít formát s malými písmeny (lowercased), s velkými písmeny na začátku slov (ProperCased) nebo s prvním písmenem malým a ostatními velkými (camelCased).

- Argumenty: Všechny názvy argumentů předávaných do metod jsou malými písmeny (lowercased).

- Data: Všechny objekty představující datum jsou předávány a vraceny jako nativní objekty Pythonu typu datetime.datetime.

- Pole: Jednorozměrná pole jsou předávána a vracena jako n-tice (což je nezměnitelný objekt). Dvourozměrná pole jsou předávána a vracena jako n-tice n-tic.

- None: Klíčové slovo Pythonu None odpovídá v Basicu Null, Empty nebo Nothing.

- Objekty UNO: Všechny struktury UNO se mezi Basicem a Pythonem předávají bez jakýchkoliv změn.

- Ladění: Nastane-li ve skriptu Pythonu využívajícím knihovnu ScriptForge chyba, chybová zpráva poskytnutá prostředím Pythonu obsahuje řádek kódu, který chybu vyvolal. V chybových zprávách Basicu tato informace není.

Další informace o skriptech Pythonu v LibreOffice naleznete na stránce Nápověda pro skripty Pythonu v LibreOffice.

## Úprava skriptů Pythonu ve vývojových prostředích (IDE)

Ve vývojových prostředích (IDE) s příslušnou funkcí lze získat pro Python typovou nápovědu týkající se veřejných metod a vlastností knihovny ScriptForge. Při úpravě uživatelského skriptu se zobrazí:

- se při najetí na instanci, metodu, nebo vlastnost objektu zobrazí podrobný popis.

- po zapsání "." za instanci objektu se zobrazí rozbalovací pole s výpisem všech dostupných rozhraní.

- po zapsání závorky za názvem metody se spustí doplňování kódu a zobrazí se argumenty této metody.

Typová nápověda se zobrazí pouze tehdy, je-li v názvech upravovaných metod a vlastností použita správná velikost písmen.

## Spouštění skriptů Pythonu v LibreOffice

Podle toho, čeho hodláte dosáhnout, můžete zvolit jeden z následujících přístupů, jak spouštět skripty Pythonu v LibreOffice:

- Spouštět skripty v rámci aktuálního procesu LibreOffice: Skripty Pythonu jsou spouštěny v rámci procesu LibreOffice volbou z nabídky Nástroje - Makra - Spustit makro nebo pomocí rozšíření APSO, který se volají uživatelské skripty uložené ve složce se skripty Pythonu. Shell Pythonu APSO můžete také využít pro interaktivní spouštění skriptů Pythonu.

- Spouštět skripty odděleně od procesu LibreOffice: Skripty Pythonu se spouští z externího procesu, který se připojí k běžícímu procesu LibreOffice pomocí soketu.

Plánujete-li spouštět skripty v rámci procesu LibreOffice, doporučuje se nainstalovat rozšíření APSO (Alternative Script Organizer for Python). K vývoji skriptů Pythonu mimo LibreOffice však můžete zvolit svoje oblíbené integrované vývojové prostředí (IDE).

## Spouštění skriptů v rámci procesu LibreOffice

### Pomocí rozšíření APSO

Nejsnazším způsobem jak začít v LibreOffice se skripty Pythonu, je nainstalovat rozšíření APSO. Po instalaci otevřete nějakou aplikaci LibreOffice a zvolte Nástroje - Makra - Organize Python scripts.

V hlavním okně APSO zvolte Menu - Python shell.

APSO můžete otevřít také výchozí zkratkou Alt+Shift+F11.

Poté můžete začít psát příkazy Pythonu, po provedení každého řádku kódu se v shellu vypíše odpovídající výstup.

Abyste mohli začít používat knihovnu ScriptForge, je nutné importovat metodu CreateScriptService, díky níž budete moci přistupovat k službám poskytovaným touto knihovnou. V níže uvedeném příkladu se používá služba Basic pro zobrazení dialogu.

        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        bas.MsgBox("Hello!")

Výše uvedený příklad spustíte tak, že postupně po jedné zadáte řádky do shellu Pythonu a po každé stisknete klávesu Enter.

Spouštět můžete příkazy Pythonu používající libovolnou službu ScriptForge. Následující část kódu například vytvoří prázdné okno Writeru pomocí služby UI.

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Writer")

### Vytváření souborů se skripty Pythonu

Vlastní skripty Pythonu můžete vytvářet a upravovat ve svém oblíbeném textovém editoru. Později je zavoláte z jakékoliv aplikace LibreOffice.

Prvním krokem je zjistit, kde jsou uloženy uživatelské skripty. To je popsáno na stránce Uspořádání a umístění skriptů Pythonu.

Poté můžete ve složce s uživatelskými skripty Pythonu vytvořit textový soubor, například sf_test.py, a začít se psaním skriptů.

Následuje jednoduchý příklad, v němž se získá z buňky Calcu číselná hodnota a zvětší se o 1. Do souboru sf_test.py přepište následující kód.

        from scriptforge import CreateScriptService
        doc = CreateScriptService("Calc")

        def increment_cell(args=None):
            value = doc.GetValue("A1")
            value += 1
            doc.SetValue("A1", value)

        g_exportedScripts = (increment_cell, )

V příkladu je vytvořena funkce increment_cell. Proměnná g_exportedScripts je n-tice určující, které funkce se v LibreOffice zobrazí jako uživatelské skripty.

Chcete-li tento skript spustit v dokumentu Calcu:

1. Vytvořte nebo otevřete soubor Calcu.

2. Zadejte do buňky "A1" na aktuálním listu libovolnou číselnou hodnotu.

3. Zvolte Nástroje - Makra - Spustit makro.

4. Ve výběru knihovny zvolte Moje makra - sf_test. Poté vyberte ze seznamu Název makra funkci increment_cell.

5. Klepněte na Spustit. Hodnota v buňce "A1" se zvětšila o 1.

Pro spouštění skriptů Pythonu můžete použít také APSO:

1. Nejprve APSO otevřete volbou Nástroje - Makra - Organize Python scripts.

2. V seznamu maker přejděte na My macros - sf_test - increment_cell.

3. Klepněte na Execute.

## Spouštění skriptů odděleně od procesu LibreOffice

### Určení instalační složky

První krokem ke spouštění skriptů z odděleného procesu je najít složky, v níž je LibreOffice nainstalován. Lze to provést několika způsoby, ScriptForge ale nabízí rychlou možnost, jak cestu k instalaci identifikovat. Za tím účelem otevřete shell Pythonu APSO a zadejte do něj:

        from scriptforge import CreateScriptService
        fs = CreateScriptService("FileSystem")
        fs.FileNaming = "SYS"
        inst_dir = fs.InstallFolder
        print(inst_dir)

Výstupem výše uvedeného kódu je základní adresář, v němž je LibreOffice nainstalován. K výsledné cestě potřebujete přidat podsložku „program“, abyste získali základní složku, z níž budete spouštět v odděleném procesu skripty Pythonu.

Jako výsledek výše uvedeného kódu Pythonu jste získali například cestu /usr/lib/libreoffice/. Poté je cestou pro spouštění skriptů Pythonu /usr/lib/libreoffice/program.

### Spuštění LibreOffice s nastavením soketů

Abyste mohli spouštět skripty Pythonu z odděleného procesu, je nutné spustit LibreOffice s několika dalšími parametry, které určují název hostitele a port, pomocí kterého bude externí proces komunikovat s procesem s aplikací LibreOffice.

Otevřete příkazový řádek operačního systému, přejděte v něm do složky „program“ v instalačním adresáři LibreOffice a zadejte:

./soffice --accept='socket,host=localhost,port=2021;urp;'

Tento příkaz spustí LibreOffice s otevřeným komunikačním kanálem, prostřednictvím kterého s ním mohou jiné procesy vyměňovat zprávy.

Výše uvedený příkaz otevře úvodní obrazovku LibreOffice. Chcete-li otevřít určitou aplikaci, například Writer, přidejte k příkazu přepínač --writer.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Poznamenejte si parametry host a port, které mají v tomto příkladu hodnoty localhost a 2021.

### Spuštění externího shellu Pythonu

Spusťte shell Pythonu ze složky program v cestě s instalací LibreOffice. Instalační cestu zjistíte podle postupu popsaného výše.

V systému Linux / MacOS:

$ cd /usr/lib/libreoffice/program

$ python

V systému Windows:

$ cd C:\Program Files\LibreOffice\program\

$ python.exe

Otevře se shell Pythonu, v němž můžete zadávat příkazy, které se provedou v LibreOffice. Nejprve je ale nutné nastavit soketové připojení.

        from scriptforge import ScriptForge, CreateScriptService
        ScriptForge(hostname='localhost', port=2021)

V případě chyb při importu souborů scriptforge.py nebo uno.py si přečtete níže uvedenou část Nastavení PYTHONPATH.

Na druhém řádku výše uvedeného kódu je určeno nastavení host a port, díky němuž může shell Pythonu komunikovat se spuštěným procesem LibreOffice, který byl otevřen se stejným nastavením soketů.

Poté můžete spouštět další příkazy Pythonu, budou moci komunikovat s procesem LibreOffice. Například:

        ui = CreateScriptService("UI")
        bas = CreateScriptService("Basic")
        doc = ui.OpenDocument("~/Documents/myFile.ods")
        bas.MsgBox(doc.DocumentType)

### Nastavení PYTHONPATH

V závislosti na konfiguraci operačního systému bude potřeba nastavit proměnnou prostředí PYTHONPATH, aby bylo možné importovat knihovnu scriptforge.py, která dále vyžaduje import knihovny uno.py.

Pomocí vyhledávání v operačním systému zjistěte adresáře, kde se tyto soubory nacházejí.

Například ve výchozí instalaci systému Ubuntu se tyto soubory mohou nacházet v těchto umístěních:

- scriptforge.py: v /usr/lib/libreoffice/program

- uno.py: v /usr/lib/python3/dist-packages

V tomto případě nastavte před spuštěním interpretu Pythonu proměnnou prostředí PYTHONPATH následovně:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

Umístění těchto souborů se liší v závislosti na operačním systému a způsobu, jakým byl LibreOffice nainstalován.

Související témata

Knihovna ScriptForge

Nápověda pro skripty Pythonu v LibreOffice

Spuštění LibreOffice s parametery