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

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

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.

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.

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

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.

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.

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

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.

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

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.

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.

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.

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

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.

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.

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)

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.

session.GetPDFExportOptions(): obj

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.

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

unoobject: obiekt do sprawdzenia.

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

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

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.

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

unoobject: obiekt do sprawdzenia.

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

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

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.

session.OpenURLInBrowser(url: str)

url: adres URL do otwarcia.

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

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

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.

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

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.

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

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.

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

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.

session.SetPDFExportOptions(pdfoptions: obj): bool

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

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.

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

unoobject: obiekt do sprawdzenia.

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

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.

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

unoobject: obiekt do sprawdzenia.

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

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.

session.UnoObjectType(unoobject: uno): str

unoobject: obiekt do zidentyfikowania.

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"

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.

session.WebService(uri: str): str

uri: adres URI usługi internetowej.

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

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.