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.