Obsah

# Služba ScriptForge.Session

Služba Session sdružuje různé obecné metody týkající se:

- prostředí instalace nebo spouštění

- zkoumání objektů UNO

- volání externích skriptů nebo programů

## Volání služby

Před používáním služby Session 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

##### V Basicu

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim session As Variant
        session = CreateScriptService("Session")

##### V Pythonu

        from scriptforge import CreateScriptService
        session = CreateScriptService("Session")

## Konstanty

Následuje seznam konstant usnadňujících nalezení knihovny obsahující skript Basicu nebo Pythonu, který se má zavolat. Používají se jako session.CONSTANT.

CONSTANT | Hodnota | Kde najít knihovnu? | Použitelné na
--- | --- | --- | ---
SCRIPTISEMBEDDED | "document" | v dokumentu | Basic + Python
SCRIPTISAPPLICATION | "application" | v jakékoliv sdílené knihovně | Basic
SCRIPTISPERSONAL | "user" | ve skupině Moje makra | Python
SCRIPTISPERSOXT | "user:uno_packages" | v rozšíření nainstalovaném pro aktuálního uživatele | Python
SCRIPTISSHARED | "share" | ve skupině Makra aplikace | Python
SCRIPTISSHAROXT | "share:uno_packages" | v rozšíření nainstalovaném pro všechny uživatele | Python
SCRIPTISOXT | "uno_packages" | v rozšíření, o němž není známo, jak je nainstalováno | Python

Seznam metod služby Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

Metody Execute... služby Session se chovají následovně:
Argumenty jsou předávány hodnotou. Změny provedené na argumentech volanou funkcí tedy neovlivní jejich hodnoty ve volajícím skriptu.
Volajícímu skriptu se vrátí jediná hodnota nebo pole hodnot.

## ExecuteBasicScript

Spustí skript Basicu určený názvem a umístěním a získá jeho výsledek, existuje-li nějaký.

Jestliže skript nic nevrátí, což je případ procedur definovaných klíčovým slovem Sub, návratovou hodnotou je Empty.

### Syntaxe:

session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any

### Parametry:

scope: Řetězec udávající místo uložení skriptu. Může se jednat buď o řetězec "document" (konstanta session.SCRIPTISEMBEDDED), nebo "application" (konstanta session.SCRIPTISAPPLICATION).

script: Řetězec udávající skript, který se má zavolat, ve formátu "knihovna.modul.metoda"; rozlišuje se u něj velikost písmen.

- Je-li to nezbytné, knihovna se načte do paměti.

- Modul nemůže být modulem třídy.

- Metoda může být typu Sub nebo Function.

args: Argumenty, které se mají předat volanému skriptu.

### Příklad:

Funkce Basicu pojmenovaná DummyFunction je uložena v části "Moje makra" v knihovně "Standard" a modulu pojmenovaném "Module1".

Tato jednoduchá funkce přijímá dvě vstupní celočíselné hodnoty v1 a v2 a vrací součet všech hodnot posloupnosti začínající v1 a končící v2.

        Function DummyFunction(v1 as Integer, v2 as Integer) As Long
            Dim result as Long, i as Integer
            For i = v1 To v2
                result = result + i
            Next i
            DummyFunction = result
        End Function

Následující příklad ukazuje, jak funkci DummyFunction volat ze skriptů Basicu a Pythonu.

##### V Basicu

        Dim session : session = CreateScriptService("Session")
        Dim b_script as String, result as Long
        b_script = "Standard.Module1.DummyFunction"
        result = session.ExecuteBasicScript("application", b_script, 1, 10)
        MsgBox result ' 55

##### V Pythonu

        session = CreateScriptService("Session")
        bas = CreateScriptService("Basic")
        b_script = 'Standard.Module1.DummyFunction'
        result = session.ExecuteBasicScript('application', b_script, 1, 10)
        bas.MsgBox(result) # 55

## ExecuteCalcFunction

Spustí funkci Calcu určenou jejím anglickým názvem a využívající zadané argumenty.
Jsou-li argumenty pole, funkce se provede jako maticový vzorec.

### Syntaxe:

session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any

### Parametry:

calcfunction: Anglický název funkce Calcu, která se má zavolat.

args: Argumenty, které se mají volané funkci Calcu předat. Každý argument musí být řetězec, číselná hodnota nebo pole polí kombinující tyto typy.

### Příklad:

##### V Basicu

        session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) ' 4
        session.ExecuteCalcFunction("ABS", Array(Array(-1, 2, 3), Array(4, -5, 6), Array(7, 8, -9)))(2)(2) ' 9
        session.ExecuteCalcFunction("LN", -3)
        ' Nastane chyba.

##### V Pythonu

        session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) # 4
        session.ExecuteCalcFunction("ABS", ((-1, 2, 3), (4, -5, 6), (7, 8, -9)))[2][2] # 9
        session.ExecuteCalcFunction("LN", -3)

## ExecutePythonScript

Spustí skript Pythonu určený názvem a umístěním a získá jeho výsledek, existuje-li nějaký. Výsledkem může být jediná hodnota nebo pole hodnot.

Není-li skript nalezen nebo nic nevrací, návratovou hodnotou je Empty.

Za tím účelem skriptovací rozhraní z rozhraní pro programování aplikací (API) LibreOffice umožňuje spouštění skriptů mezi Pythonem a Basicem, případně mezi dalšími podporovanými programovacími jazyky. Ve voláních lze předávat oběma směry argumenty za předpokladu, že se jedná o primitivní datové typy rozpoznatelné oběma jazyky a že je skriptovací rozhraní umí správně převést.

### Syntaxe:

session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any

### Parametry:

scope: Některá z relevantních konstant uvedených v seznamu výše. Výchozí hodnotou je session.SCRIPTISSHARED.

script: Řetězec, u nějž se rozlišuje velikost písmen, ve formátu "knihovna/modul.py$metoda", "modul.py$metoda" nebo "mojeRozsireni.oxt|mujSkript|modul.py$metoda".

- knihovna: Cesta ke složce s modulem Pythonu.

- mujSkript: Složka obsahující modul Pythonu.

- modul.py: Modul Pythonu.

- method: Funkce Pythonu.

args: Argumenty, které se mají předat volanému skriptu.

### Příklad:

Níže definovaná funkce Pythonu odd_integers vytváří seznam lichých čísel mezi hodnotami v1 a v2. Tato funkce je uložena v souboru pojmenovaném my_macros.py ve složce uživatelských skriptů.

        def odd_integers(v1, v2):
            odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]
            return odd_list

Podrobnosti o možnostech uložení skriptů Pythonu naleznete na stránce Uspořádání a umístění skriptů Pythonu.

Následující příklady ukazují, jak funkci odd_integers volat ze skriptů Basicu a Pythonu.

##### V Basicu

        Dim script as String, session as Object
        script = "my_macros.py$odd_integers"
        session = CreateScriptService("Session")
        Dim result as Variant
        result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
        MsgBox SF_String.Represent(result)

##### V Pythonu

        session = CreateScriptService("Session")
        script = "my_macros.py$odd_integers"
        result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
        bas.MsgBox(repr(result))

## GetPDFExportOptions

Vrátí aktuální nastavení exportu do PDF definované v dialogovém okně Možnosti PDF, které lze zobrazit volbou Soubor - Exportovat jako - Exportovat jako PDF.

Možnosti exportu nastavené v dialogovém okně Možnosti PDF se zachovávají pro budoucí použití. Metoda GetPDFExportOptions proto vrátí aktuálně definované nastavení. Aktuální možnosti exportu do PDF můžete navíc změnit metodou SetPDFExportOptions.

Tato metoda vrátí objekt Dictionary, v němž klíče představují názvy možností exportu a odpovídající hodnoty představuje aktuální nastavení exportu do PDF.

Informace o všech dostupných možnostech naleznete na wiki stránce PDF Export.

### Syntaxe:

session.GetPDFExportOptions(): obj

### Příklad:

##### V Basicu

        Dim expSettings As Object, msg As String, key As String, optLabels As Variant
        expSettings = session.GetPDFExportOptions()
        optLabels = expSettings.Keys
        For Each key in optLabels
            msg = msg + key & ": " & expSettings.Item(key) & Chr(10)
        Next key
        MsgBox msg
        ' Zoom: 100
        ' Changes: 4
        ' Quality: 90
        ' ...

Tato metoda je k dispozici pouze pro skripty Basicu.

## HasUnoMethod

Vrátí True, jestliže objekt UNO obsahuje zadanou metodu. False vrátí v případě, že metoda není nalezena nebo je argument neplatný.

### Syntaxe:

session.HasUnoMethod(unoobject: uno, methodname: str): bool

### Parametry:

unoobject: Objekt, který se má prozkoumat.

methodname: Metoda jako řetězec, u něhož se rozlišuje velikost písmen.

### Příklad:

##### V Basicu

        Dim a As Variant
        a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox session.HasUnoMethod(a, "callFunction") ' True

##### V Pythonu

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoMethod(a, "callFunction")
        bas.MsgBox(result) # True

## HasUnoProperty

Vrátí True, jestliže objekt UNO obsahuje zadanou vlastnost. False vrátí v případě, že vlastnost není nalezena nebo je argument neplatný.

### Syntaxe:

session.HasUnoProperty(unoobject: uno, propertyname: str): bool

### Parametry:

unoobject: Objekt, který se má prozkoumat.

propertyname: Vlastnost jako řetězec, u něhož se rozlišuje velikost písmen.

### Příklad:

##### V Basicu

        Dim svc As Variant
        svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox session.HasUnoProperty(svc, "Wildcards")

##### V Pythonu

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoProperty(a, "Wildcards")
        bas.MsgBox(result) # True

## OpenURLInBrowser

Otevře ve výchozím prohlížeči adresu URL (Uniform Resource Locator).

### Syntaxe:

session.OpenURLInBrowser(url: str)

### Parametry:

url: Adresa URL, která se má otevřít.

### Příklad:

        ' Basic
        session.OpenURLInBrowser("help.libreoffice.org/")

        # Python
        session.OpenURLInBrowser("help.libreoffice.org/")

## RunApplication

Spustí libovolný systémový příkaz a v případě úspěšného spuštění vrátí True.

### Syntaxe:

session.RunApplication(command: str, parameters: str): bool

### Parametry:

command: Příkaz, který se má spustit. Může se jednat o spustitelný soubor nebo o dokument, jehož typ je zaregistrován u nějaké aplikace, takže systém bude moci určit, kterou aplikaci má pro spuštění dokumentu použít. Metoda může také spouštět skripty Shellu nebo ze souboru .bat. Příkaz musí odpovídat zápisu SF_FileSystem.FileNaming.

paramters: Seznam mezerou oddělených parametrů jako jediný řetězec. Metoda zadané parametry nijak neověřuje, pouze je předá zadanému příkazu.

### Příklad:

##### V Basicu

        session.RunApplication("Notepad.exe")
        session.RunApplication("C:\\myFolder\\myDocument.odt")
        session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux

##### V Pythonu

        session.RunApplication("Notepad.exe")
        session.RunApplication(r"C:\\myFolder\\myDocument.odt")
        session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux

## SendMail

Odešle z uživatelova poštovního klienta zprávu, volitelně s přílohami. Zprávu může uživatel před odesláním upravit, nebo ji lze odeslat okamžitě.

### Syntaxe:

session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)

### Parametry:

recipient: E-mailová adresa (příjemce „komu“).

cc: Čárkami oddělený seznam e-mailových adres (příjemci „kopie“).

bcc: Čárkami oddělený seznam e-mailových adres (příjemci „skrytá kopie“).

subject: Nadpis zprávy.

body: Obsah zprávy jako neformátovaný text.

filenames: Čárkami oddělený seznam názvů souborů. Názvy musí odpovídat zápisu SF_FileSystem.FileNaming.

editmessage: Je-li True (výchozí), zprávu bude možné před odesláním upravit.

### Příklad:

##### V Basicu

        session.SendMail("someone@example.com" _
            , Cc := "b@other.fr, c@other.be" _
            , FileNames := "C:\myFile1.txt, C:\myFile2.txt")

##### V Pythonu

        session.SendMail("someone@example.com",
                         cc="john@other.fr, mary@other.be"
                         filenames=r"C:\myFile1.txt, C:\myFile2.txt")

## SetPDFExportOptions

Změní nastavení exportu do PDF definované v dialogovém okně Možnosti PDF, které lze zobrazit volbou Soubor - Exportovat jako - Exportovat jako PDF.

Zavolání této metody změní hodnoty nastavené v okně Možnosti PDF, které používá metoda ExportAsPDF ze služby Document.

V případě úspěšné změny vrátí metoda True.

Informace o všech dostupných možnostech naleznete na wiki stránce PDF Export.

### Syntaxe:

session.SetPDFExportOptions(pdfoptions: obj): bool

### Parametry:

pdfoptions: Objekt Dictionary určující nastavení exportu do PDF, které se má změnit. Každá dvojice klíč-hodnota představuje možnost exportu, v okně bude nastavena hodnota.

### Příklad:

##### V Basicu

V následujícím příkladu je změněno maximální rozlišení obrázků ze 150 DPI a aktuální dokument je vyexportován jako soubor PDF.

        Dim newSettings As Object, oDoc As Object
        Set oDoc = CreateScriptService("Document")
        Set newSettings = CreateScriptService("Dictionary")
        newSettings.Add("ReduceImageResolution", True)
        newSettings.Add("MaxImageResolution", 150)
        session.SetPDFExportOptions(newSettings)
        oDoc.ExportAsPDF("C:\Documents\myFile.pdf", Overwrite := True)

Tato metoda je k dispozici pouze pro skripty Basicu.

## UnoMethods

Vrátí seznam metod, které lze zavolat z objektu UNO. Seznam představuje pole řetězců začínající od 0, které může být prázdné.

### Syntaxe:

session.UnoMethods(unoobject: uno): str[0..*]

### Parametry:

unoobject: Objekt, který se má prozkoumat.

### Příklad:

##### V Basicu

        Dim svc : svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        Dim methods : methods = session.UnoMethods(svc)
        Dim msg as String
        For Each m in methods
            msg = msg & m & Chr(13)
        Next m
        MsgBox msg

##### V Pythonu

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        methods = session.UnoMethods(a)
        msg = "\n".join(methods)
        bas.MsgBox(msg)

## UnoProperties

Vrátí seznam vlastností objektu UNO. Seznam představuje pole řetězců začínající od 0, které může být prázdné.

### Syntaxe:

session.UnoProperties(unoobject: uno): str[0..*]

### Parametry:

unoobject: Objekt, který se má prozkoumat.

### Příklad:

##### V Basicu

        Dim svc As Variant
        svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
        MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True

##### V Pythonu

        bas = CreateScriptService("Basic")
        svc = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        properties = session.UnoProperties(a)
        b = "Wildcards" in properties
        bas.MsgBox(str(b)) # True

## UnoObjectType

Zjistí typ objektu UNO jako řetězec.

### Syntaxe:

session.UnoObjectType(unoobject: uno): str

### Parametry:

unoobject: Objekt, který se má prozkoumat.

### Příklad:

##### V Basicu

        Dim svc As Variant, txt As String
        svc = CreateUnoService("com.sun.star.system.SystemShellExecute")
        txt = session.UnoObjectType(svc) ' "com.sun.star.comp.system.SystemShellExecute"
        svc = CreateUnoStruct("com.sun.star.beans.Property")
        txt = session.UnoObjectType(svc) ' "com.sun.star.beans.Property"

##### V Pythonu

        bas = CreateScriptService("Basic")
        svc = bas.CreateUnoService("com.sun.star.system.SystemShellExecute")
        txt = session.UnoObjectType(svc) # "com.sun.star.comp.system.SystemShellExecute"
        svc = bas.CreateUnoService("com.sun.star.beans.Property")
        txt = session.UnoObjectType(svc) # "com.sun.star.beans.Property"

## WebService

Získá webový obsah z adresy URI.

### Syntaxe:

session.WebService(uri: str): str

### Parametry:

uri: Adresa URI webové služby.

### Příklad:

##### V Basicu

        session.WebService("wiki.documentfoundation.org/api.php?" _
            & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")

##### V Pythonu

        session.WebService(("wiki.documentfoundation.org/api.php?"
                           "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))

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

Funkce Array

Použití funkcí Calcu v makrech

Volání skriptů Pythonu z Basicu

Služba ScriptForge.Basic

Služba ScriptForge.FileSystem