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:

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

Instrukcja Array

Korzystanie z funkcji Calc w makrach

Wywoływanie skryptów Pythona z Basic

Usługa ScriptForge.Basic

Usługa ScriptForge.FileSystem