Obsah
Rejstřík 🔎︎

# 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

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

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

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

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

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

- modul.py: Modul Pythonu.

- method: Funkce Pythonu.

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

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.

Související témata

Funkce Array

Volání funkcí Calcu

Volání skriptů Pythonu z Basicu

Služba ScriptForge.FileSystem