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 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.
Run Scripts separately from the LibreOffice process: Python scripts are executed from an external process that connects to an ongoing LibreOffice process using a pipe or a socket.

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:

Vytvořte nebo otevřete soubor Calcu.
Zadejte do buňky "A1" na aktuálním listu libovolnou číselnou hodnotu.
Zvolte Nástroje - Makra - Spustit makro.
Ve výběru knihovny zvolte Moje makra - sf_test. Poté vyberte ze seznamu Název makra funkci increment_cell.
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:

Nejprve APSO otevřete volbou Nástroje - Makra - Organize Python scripts.
V seznamu maker přejděte na My macros - sf_test - increment_cell.
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.

Start LibreOffice with pipe or socket settings

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.

Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type either:

./soffice --accept='pipe,name=libreoffice;urp;'

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

Either command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

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

Take note of the name, or host and port parameters, which in this example are libreoffice, or localhost and 2021, respectively.

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

This will open the Python shell and now you can start typing commands that will be executed by LibreOffice. But first you need to set up the pipe or the socket connection. The ScriptForge() statement below must precede the very first call to CreateScriptService().

Run either:


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='libreoffice')


    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.

The second line of code above defines the pipe or host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same pipe or socket settings.

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.

Knihovna ScriptForge

Nápověda pro skripty Pythonu v LibreOffice

Spuštění LibreOffice s parametery