Spis treści

# Usługa ScriptForge.Session

Usługa Session gromadzi różne metody ogólnego przeznaczenia dotyczące:

- środowiska instalacji lub wykonania

- eksploracji obiektów UNO

- wywoływania zewnętrznych skryptów lub programów

## Wywoływanie usługi

Przed użyciem usługi Session należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

##### W języku Basic

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

##### W języku Python

        from scriptforge import CreateScriptService
        session = CreateScriptService("Session")

## Stałe

Poniżej znajduje się lista dostępnych stałych ułatwiających wyznaczenie biblioteki zawierającej skrypt Basic lub Python do wywołania. Użyj ich jako session.CONSTANT.

CONSTANT | Wartość | Gdzie znaleźć bibliotekę? | Dotyczy
--- | --- | --- | ---
SCRIPTISEMBEDDED | "document" | w dokumencie | Basic + Python
SCRIPTISAPPLICATION | "application" | w dowolnej bibliotece współdzielonej | Basic
SCRIPTISPERSONAL | "user" | w Moich makrach | Python
SCRIPTISPERSOXT | "user:uno_packages" | w rozszerzeniu zainstalowanym dla bieżącego użytkownika | Python
SCRIPTISSHARED | "share" | w Makrach aplikacji | Python
SCRIPTISSHAROXT | "share:uno_packages" | w rozszerzeniu zainstalowanym dla wszystkich użytkowników | Python
SCRIPTISOXT | "uno_packages" | w rozszerzeniu, ale parametry instalacji są nieznane | Python

Lista metod w usłudze Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

Metody Execute... w usłudze Session zachowują się następująco:
Argumenty są przekazywane przez wartość. Zmiany dokonane przez wywoływaną funkcję w argumentach nie aktualizują ich wartości w skrypcie wywołującym.
Do skryptu wywołującego zwracana jest pojedyncza wartość lub tablica wartości.

## ExecuteBasicScript

Wykonaj skrypt BASIC, podając jego nazwę i lokalizację, i pobierz jego wynik, jeśli taki istnieje.

Jeśli skrypt nic nie zwraca, co ma miejsce w przypadku procedur zdefiniowanych za pomocą Sub, zwracaną wartością jest Empty.

### Składnia:

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

### Parametry:

scope: ciąg znaków określający miejsce przechowywania skryptu. Może to być "document" (stała session.SCRIPTISEMBEDDED) lub "application (stała session.SCRIPTISAPPLICATION).

script: ciąg znaków określający skrypt, który ma zostać wywołany, w formacie "library.module.method" jako ciąg znaków, w którym uwzględniana jest wielkość liter.

- W razie potrzeby biblioteka jest ładowana do pamięci.

- Moduł nie może być modułem klasy.

- Metodą może być Sub lub Function.

args: argumenty, które mają zostać przekazane do wywoływanego skryptu.

### Przykład:

Rozważ następującą funkcję Basic o nazwie DummyFunction, która jest przechowywana w "Moich makrach" w bibliotece "Standard" w module o nazwie "Module1".

Funkcja po prostu przyjmuje dwie wartości całkowite v1 i v2 oraz zwraca sumę wszystkich wartości zaczynających się od v1 i kończących się na 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

Poniższe przykłady pokazują, jak wywołać DummyFunction ze skryptów Basic i Python.

##### W języku Basic

        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

##### W języku Python

        session = CreateScriptService("Session")
        bas = CreateScriptService("Basic")
        b_script = 'Standard.Module1.DummyFunction'
        result = session.ExecuteBasicScript('application', b_script, 1, 10)
        bas.MsgBox(result) # 55

## ExecuteCalcFunction

Wykonaj funkcję Calc, używając jej angielskiej nazwy i w oparciu o podane argumenty.
Jeśli argumentami są tablice, funkcja jest wykonywana jako formuła tablicowa.

### Składnia:

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

### Parametry:

calcfunction: nazwa funkcji Calc, która ma zostać wywołana, w języku angielskim.

args: argumenty, które mają zostać przekazane do wywoływanej funkcji Calc. Każdy argument musi być ciągiem znaków, wartością liczbową lub tablicą tablic łączących te typy.

### Przykład:

##### W języku Basic

        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)
        ' Generuje błąd.

##### W języku Python

        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

Uruchamia skrypt Pythona określony przez nazwę i lokalizację i pobiera jego wynik, jeśli taki istnieje. Wynikiem może być pojedyncza wartość lub tablica wartości.

Jeśli skrypt nie zostanie znaleziony lub nic nie zwróci, zwrócona wartość będzie Empty.

Struktura skryptów API (Application Programming Interface) LibreOffice obsługuje międzyjęzykowe wykonywanie skryptów między językami Python i Basic lub innymi obsługiwanymi językami programowania. Argumenty mogą być przekazywane tam iz powrotem między wywołaniami, pod warunkiem, że reprezentują prymitywne typy danych rozpoznawane przez oba języki i przy założeniu, że środowisko skryptowe odpowiednio je konwertuje.

### Składnia:

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

### Parametry:

scope: jedna z odpowiednich stałych wymienionych powyżej. Wartość domyślna to session.SCRIPTISSHARED.

script: albo "library/module.py$method", "module.py$method", albo "myExtension.oxt|myScript|module.py$method" jako ciąg znaków, w którym rozróżniana jest wielkość liter.

- library: ścieżka folderu do modułu Python.

- myScript: folder zawierający moduł Pythona.

- module.py: moduł Pythona.

- method: funkcja Pythona.

args: argumenty, które mają zostać przekazane do wywoływanego skryptu.

### Przykład:

Rozważmy zdefiniowaną poniżej funkcję Pythona odd_integers, która tworzy listę z nieparzystymi wartościami całkowitymi pomiędzy v1 i v2. Załóżmy, że ta funkcja jest przechowywana w pliku o nazwie my_macros.py w folderze skryptów użytkownika.

        def odd_integers(v1, v2):
            odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]
            return odd_list

Przeczytaj stronę pomocy Organizacja i lokalizacja skryptów Pythona, aby dowiedzieć się więcej o tym, gdzie można przechowywać skrypty Pythona.

Poniższe przykłady pokazują, jak wywołać funkcję odd_integers ze skryptów Basic i Python.

##### W języku Basic

        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)

##### W języku Python

        session = CreateScriptService("Session")
        script = "my_macros.py$odd_integers"
        result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
        bas.MsgBox(repr(result))

## GetPDFExportOptions

Zwraca bieżące ustawienia eksportu PDF zdefiniowane w oknie dialogowym Opcje PDF, do którego można uzyskać dostęp, wybierając Plik - Eksportuj jako - Eksportuj jako PDF.

Opcje eksportu ustawione w oknie dialogowym Opcje PDF zostaną zachowane do wykorzystania w przyszłości. Dlatego GetPDFExportOptions zwraca aktualnie zdefiniowane ustawienia. Ponadto użyj SetPDFExportOptions, aby zmienić bieżące opcje eksportu PDF.

Ta metoda zwraca obiekt Dictionary, w którym każdy klucz reprezentuje opcje eksportu, a odpowiadające im wartości to bieżące ustawienia eksportu do pliku PDF.

Przeczytaj stronę wiki dotyczącą eksportu PDF, aby dowiedzieć się więcej o wszystkich dostępnych opcjach.

### Składnia:

session.GetPDFExportOptions(): obj

### Przykład:

##### W języku Basic

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

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

## HasUnoMethod

Zwraca True, jeśli obiekt UNO zawiera podaną metodę. Zwraca False, gdy nie znaleziono metody lub gdy argument jest nieprawidłowy.

### Składnia:

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

### Parametry:

unoobject: obiekt do sprawdzenia.

methodname: metoda jako ciąg znaków, w którym rozróżniana jest wielkość liter

### Przykład:

##### W języku Basic

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

##### W języku Python

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoMethod(a, "callFunction")
        bas.MsgBox(result) # True

## HasUnoProperty

Zwraca True, jeśli obiekt UNO ma podaną właściwość. Zwraca False, gdy właściwość nie została znaleziona lub gdy argument jest nieprawidłowy.

### Składnia:

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

### Parametry:

unoobject: obiekt do sprawdzenia.

propertyname: właściwość jako ciąg znaków, w którym rozróżniana jest wielkość liter

### Przykład:

##### W języku Basic

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

##### W języku Python

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        result = session.HasUnoProperty(a, "Wildcards")
        bas.MsgBox(result) # True

## OpenURLInBrowser

Otwórz URL (Uniform Resource Locator) w domyślnej przeglądarce.

### Składnia:

session.OpenURLInBrowser(url: str)

### Parametry:

url: adres URL do otwarcia.

### Przykład:

        ' Basic
        session.OpenURLInBrowser("help.libreoffice.org/")

        # Python
        session.OpenURLInBrowser("help.libreoffice.org/")

## RunApplication

Wykonuje dowolne polecenie systemowe i zwraca True, jeśli zostało pomyślnie uruchomione.

### Składnia:

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

### Parametry:

polecenie: polecenie do wykonania. Może to być plik wykonywalny lub dokument zarejestrowany w aplikacji, dzięki czemu system wie, jaką aplikację uruchomić dla tego dokumentu. Ta metoda uruchamia zarówno skrypty .bat, jak i powłoki. Polecenie musi być wyrażone w bieżącej notacji SF_FileSystem.FileNaming.

parameters: lista parametrów oddzielonych spacjami w postaci pojedynczego ciągu. Metoda nie weryfikuje podanych parametrów, a jedynie przekazuje je do podanego polecenia.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## SendMail

Wyślij wiadomość – z opcjonalnymi załącznikami – do odbiorców z klienta pocztowego użytkownika. Wiadomość może być edytowana przez użytkownika przed wysłaniem lub może zostać wysłana od razu.

### Składnia:

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

### Parametry:

recipient: adres e-mail (odbiorca „do”).

cc: rozdzielana przecinkami lista adresów e-mail („odbiorców kopii”).

bcc: rozdzielana przecinkami lista adresów e-mail (odbiorców „ślepej kopii”).

subject: nagłówek wiadomości.

body: treść wiadomości jako niesformatowany tekst.

filenames: rozdzielona przecinkami lista nazw plików. Każda nazwa pliku musi być zgodna z notacją SF_FileSystem.FileNaming.

editmessage: jeśli True (domyślnie), wiadomość jest edytowana przed wysłaniem.

### Przykład:

##### W języku Basic

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

##### W języku Python

        session.SendMail("someone@example.com",
                         cc="john@other.fr, mary@other.be"
                         filenames=r"C:\myFile1.txt, C:\myFile2.txt")

## SetPDFExportOptions

Modyfikuje ustawienia eksportu PDF zdefiniowane w oknie dialogowym Opcje PDF, do którego można uzyskać dostęp, wybierając Plik - Eksportuj jako - Eksportuj jako PDF.

Wywołanie tej metody powoduje zmianę rzeczywistych wartości ustawionych w oknie dialogowym Opcje PDF, które są używane przez metodę ExportAsPDF z usługi Document.

Ta metoda zwraca wartość True, jeśli operacja się powiedzie.

Przeczytaj stronę wiki dotyczącą eksportu PDF, aby dowiedzieć się więcej o wszystkich dostępnych opcjach.

### Składnia:

session.SetPDFExportOptions(pdfoptions: obj): bool

### Parametry:

pdfoptions: obiekt Dictionary określający ustawienia eksportu PDF do zmiany. Każda para klucz-wartość reprezentuje opcję eksportu, wartość zostanie ustawiona w oknie.

### Przykład:

##### W języku Basic

Poniższy przykład zmienia maksymalną rozdzielczość obrazu na 150 dpi i eksportuje bieżący dokument jako plik 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)

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

## UnoMethods

Zwraca listę metod, które można wywołać z obiektu UNO. Lista jest tablicą ciągów znaków liczoną od zera i może być pusta.

### Składnia:

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

### Parametry:

unoobject: obiekt do sprawdzenia.

### Przykład:

##### W języku Basic

        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

##### W języku Python

        bas = CreateScriptService("Basic")
        a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
        methods = session.UnoMethods(a)
        msg = "\n".join(methods)
        bas.MsgBox(msg)

## UnoProperties

Zwraca listę właściwości obiektu UNO. Lista jest tablicą ciągów znaków liczoną od zera i może być pusta.

### Składnia:

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

### Parametry:

unoobject: obiekt do sprawdzenia.

### Przykład:

##### W języku Basic

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

##### W języku Python

        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

Zidentyfikuj typ obiektu UNO jako ciąg.

### Składnia:

session.UnoObjectType(unoobject: uno): str

### Parametry:

unoobject: obiekt do zidentyfikowania.

### Przykład:

##### W języku Basic

        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"

##### W języku Python

        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

Pobierz zawartość internetową z identyfikatora URI.

### Składnia:

session.WebService(uri: str): str

### Parametry:

uri: adres URI usługi internetowej.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Instrukcja Array

Korzystanie z funkcji Calc w makrach

Wywoływanie skryptów Pythona z Basic

Usługa ScriptForge.Basic

Usługa ScriptForge.FileSystem