Služba ScriptForge.Session

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

Volání služby


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

Tato služba je plně podporována v jazycích Basic i Python. Všechny příklady jsou uvedeny v programovacím jazyce Basic a lze je snadno převést na Python.


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
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

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

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

Syntaxe:


      session.ExecuteBasicScript([Scope As String], Script As String[, arg0 As Variant, ...]) As Variant
   

Parametry:

Scope: "document", "application" nebo některá z relevantních konstant session.CONSTANTS.

Script: Skript, který se má zavolat, ve formátu "knihovna.modul.metoda" jako řetězec, u nějž se rozlišuje 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.

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

Příklad:


      session.ExecuteBasicScript(, "XrayTool._Main.Xray", CreateUnoService("com.sun.star.util.TextSearch"))
      ' Xray nevrátí žádnou hodnotu
   

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 As String, arg0, ...) As Variant
   

Parametry:

CalcFunction: Anglický název funkce Calcu, která se má spustit.

arg0, ...: 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:


      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.
   

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] As String, Script As String[, arg0 As Variant, ...]) As Variant
   

Parametry:

Scope: Některá z relevantních konstant session.CONSTANTS. Výchozí = 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".

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

Příklad:


      session.ExecutePythonScript(session.SCRIPTISSHARED, "Capitalise.py$getNewString", "Abc") ' "abc"
   

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 As Object, MethodName As String) As Boolean
   

Parametry:

UnoObject: Objekt, který se má prozkoumat.

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

Příklad:


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

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 As Object, PropertyName As String) As Boolean
   

Parametry:

UnoObject: Objekt, který se má prozkoumat.

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

Příklad:


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

OpenURLInBrowser

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

Syntaxe:


      session.OpenURLInBrowser(URL As String)
   

Parametry:

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

Příklad:


      session.OpenURLInBrowser("https://docs.python.org/3/library/webbrowser.html")
   

RunApplication

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

Syntaxe:


      session.RunApplication(Command As String, Parameters As String) As Boolean
   

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:


      session.RunApplication("Notepad.exe")
      session.RunApplication("C:\myFolder\myDocument.odt")
      session.RunApplication("kate", "/home/me/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 As String, [Cc As String], [Bcc As String], [Subject As String], [Body As String], [FileNames As String], [EditMessage As Boolean])
   

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:


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

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 As Object) As Variant
   

Parametry:

UnoObject: Objekt, který se má prozkoumat.

Příklad:


      Dim a As Variant
      a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
      MsgBox SF_Array.Contains(session.UnoMethods(a), "callFunction")
   

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 As Object) As Variant
   

Parametry:

UnoObject: Objekt, který se má prozkoumat.

Příklad:


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

UnoObjectType

Zjistí typ objektu UNO jako řetězec.

Syntaxe:


      session.UnoObjectType(UnoObject As Object) As String
   

Parametry:

UnoObject: Objekt, který se má prozkoumat.

Příklad:


      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"
   

WebService

Získá webový obsah z adresy URI.

Syntaxe:


      session.WebService(URI As String) As String
   

Parametry:

URI: Text URI webové služby.

Příklad:


      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.