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

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

    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.

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.

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

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.

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.

    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
  

    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.

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

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.

    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.
  

    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.

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

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.

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.

    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)
  

    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.

session.GetPDFExportOptions(): obj

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

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

unoobject: Objekt, který se má prozkoumat.

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

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

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

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

unoobject: Objekt, který se má prozkoumat.

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

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

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

session.OpenURLInBrowser(url: str)

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

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

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

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

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

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

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

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.

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

    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.

session.SetPDFExportOptions(pdfoptions: obj): bool

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.

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

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

unoobject: Objekt, který se má prozkoumat.

    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
  

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

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

unoobject: Objekt, který se má prozkoumat.

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

    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.

session.UnoObjectType(unoobject: uno): str

unoobject: Objekt, který se má prozkoumat.

    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"
  

    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.

session.WebService(uri: str): str

uri: Adresa URI webové služby.

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

    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.