Usługa ScriptForge.Session

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

Wywoływanie usługi

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

note

• 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


tip

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.

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.

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
  
tip

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.

tip

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

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.

tip

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

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

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.


Prosimy o wsparcie!