Služba ScriptForge.Session

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

Volání služby

Před používáním služby Session je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

note

• 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"

v makrech LibreOffice

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


tip

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.

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

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
  
tip

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.

tip

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

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

tip

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

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"))
  
warning

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.


Podpořte nás!