Dienst ScriptForge.Session

Der Dienst Session sammelt verschiedene Allzweckmethoden zu:

der Installations- oder Ausführungsumgebung
UNO-Introspektion
dem Aufruf externer Skripte oder Programme

Dienstaufruf

Vor der Verwendung des Dienstes Session muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

In Basic


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

In Python


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

Konstanten

Nachfolgend finden Sie eine Liste der verfügbaren Konstanten, um die Bestimmung der Bibliothek zu erleichtern, die ein aufzurufendes Basic- oder Python-Skript enthält. Verwenden Sie diese als session.CONSTANT.

CONSTANT	Wert	Wo finde ich die Bibliothek?	Zutreffend
SCRIPTISEMBEDDED	"document"	im Dokument	Basic + Python
SCRIPTISAPPLICATION	"application"	in einer gemeinsam genutzten Bibliothek	Basic
SCRIPTISPERSONAL	"user"	in Meine Makros	Python
SCRIPTISPERSOXT	"user:uno_packages"	in einer für den aktuellen Benutzer installierten Erweiterung	Python
SCRIPTISSHARED	"share"	in Anwendungsmakros	Python
SCRIPTISSHAROXT	"share:uno_packages"	in einer für alle Benutzer installierten Erweiterung	Python
SCRIPTISOXT	"uno_packages"	in einer Erweiterung, aber die Installationsparameter sind unbekannt	Python

Liste der Methoden im Dienst Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod	HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions	UnoMethods UnoProperties UnoObjectType WebService

Methoden Execute… im Dienst Session verhalten sich wie folgt:
Argumente werden als Wert übergeben. Änderungen, die von der aufgerufenen Funktion an den Argumenten vorgenommen werden, aktualisieren ihre Werte im aufrufenden Skript nicht.
Ein einzelner Wert oder eine Matrix von Werten wird an das aufrufende Skript zurückgegeben.

ExecuteBasicScript

Führen Sie das BASIC-Skript mit seinem Namen und Ort aus und rufen Sie sein Ergebnis ab, falls vorhanden.

Wenn das Skript nichts zurückgibt, was bei mit Sub definierten Prozeduren der Fall ist, ist der zurückgegebene Wert Empty.

Syntax:

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

Parameter:

scope: Zeichenfolge, die festlegt, wo das Skript gespeichert wird. Es kann entweder "document" (Konstante session.SCRIPTISEMBEDDED) oder "application" (Konstante session.SCRIPTISAPPLICATION) sein.

script: Zeichenfolge, die das aufzurufende Skript im Format "library.module.method" unter Beachtung der Groß- und Kleinschreibung festlegt.

Die Bibliothek wird bei Bedarf in den Speicher geladen.
Das Modul darf kein Klassenmodul sein.
Die Methode kann ein Sub oder eine Function sein.

args: Die Argumente, die an das aufgerufene Skript übergeben werden sollen.

Beispiel:

Betrachten Sie die folgende Basic-Funktion namens DummyFunction, die in „Meine Makros“ in der Bibliothek „Standard“ innerhalb eines Moduls namens „Module1“ gespeichert ist.

Die Funktion nimmt einfach zwei ganzzahlige Werte v1 und v2 und gibt die Summe aller Werte zurück, die in v1 beginnen und in v2 enden.


    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

Die folgenden Beispiele zeigen, wie DummyFunction in Basic- und Python-Skripten aufgerufen wird.

In 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

In 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

Führt eine Calc-Funktion mit ihrem englischen Namen und basierend auf den angegebenen Argumenten aus.
Wenn die Argumente Matrizen sind, wird die Funktion als Matrixformel ausgeführt.

Syntax:

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

Parameter:

calcfunction: Der Name der aufzurufenden Calc-Funktion in Englisch.

args: Die Argumente, die an die aufgerufene Calc-Funktion übergeben werden sollen. Jedes Argument muss entweder eine Zeichenfolge, ein numerischer Wert oder eine Matrix von Matrizen sein, die diese Typen kombinieren.

Beispiel:

In 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)
    ' Erzeugt einen Fehler.

In 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

Führt das Python-Skript von seinem Speicherort und mit seinem Namen aus und ruft sein Ergebnis, falls vorhanden, ab. Das Ergebnis kann ein einzelner Wert oder eine Matrix mit Werten sein.

Wenn das Skript nicht gefunden wird oder nichts zurückgibt, ist der zurückgegebene Wert Empty.

Das Scripting-Framework der LibreOffice-Anwendungsprogrammierschnittstelle (API) unterstützt die Ausführung von Skripten zwischen Python und Basic oder anderen unterstützten Programmiersprachen. Argumente können zwischen Aufrufen hin und her übergeben werden, sofern sie primitive Datentypen darstellen, die von beiden Sprachen erkannt werden, und vorausgesetzt, dass sie vom Scripting-Framework ordnungsgemäß konvertiert werden.

Syntax:

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

Parameter:

scope: Eine der anwendbaren Konstanten, die oben aufgeführt sind. Der Standardwert ist session.SCRIPTISSHARED.

script: "Bibliothek/Modul.py$Methode", "Modul.py$Methode" oder "„meineErweiterung.oxt|meinSkript|Modul.py$Methode" als Zeichenfolge unter Beachtung der Groß-/Kleinschreibung.

library: Der Ordnerpfad zum Python-Modul.
myScript: Der Ordner, der das Python-Modul enthält.
module.py: Das Python-Modul.
method: Die Python-Funktion.

args: Die Argumente, die an das aufgerufene Skript übergeben werden sollen.

Beispiel:

Betrachten Sie die unten definierte Python-Funktion odd_integers, die eine Liste mit ungeraden ganzzahligen Werten zwischen v1 und v2 erstellt. Angenommen, diese Funktion ist in einer Datei namens my_macros.py in Ihrem Benutzerskriptordner gespeichert.


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

Lesen Sie die Hilfeseite Organisation und Speicherort von Python-Skripten, um mehr darüber zu erfahren, wo Python-Skripte gespeichert werden können.

Die folgenden Beispiele zeigen, wie die Funktion odd_integers in Basic- und Python-Skripten aufgerufen wird.

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

In Python


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

GetPDFExportOptions

Gibt die aktuellen PDF-Exporteinstellungen zurück, die im Dialog PDF-Optionen definiert sind, auf das Sie zugreifen können, indem Sie Datei – Exportieren als – Als PDF exportieren… wählen.

Die im Dialog PDF-Optionen eingestellten Exportoptionen werden für die zukünftige Verwendung beibehalten. Daher gibt GetPDFExportOptions die aktuell festgelegten Einstellungen zurück. Verwenden Sie außerdem SetPDFExportOptions, um die aktuellen PDF-Exportoptionen zu ändern.

Diese Methode gibt ein Objekt Dictionary zurück, wobei jeder Schlüssel Exportoptionen darstellt und die entsprechenden Werte die aktuellen PDF-Exporteinstellungen sind.

Lesen Sie die Wiki-Seite PDF-Export, um mehr über alle verfügbaren Optionen zu erfahren.

Syntax:

session.GetPDFExportOptions(): obj

Beispiel:

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

Diese Methode ist nur für Basic-Skripte verfügbar.

HasUnoMethod

Gibt True zurück, wenn ein UNO-Objekt die angegebene Methode enthält. Gibt False zurück, wenn die Methode nicht gefunden wird oder wenn ein Argument ungültig ist.

Syntax:

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

Parameter:

unoobject: Das zu prüfende Objekt.

methodname: Die Methode als Zeichenfolge unter Berücksichtigung der Groß- und Kleinschreibung

Beispiel:

In Basic


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

In Python


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

HasUnoProperty

Gibt True zurück, wenn ein UNO-Objekt die angegebene Eigenschaft hat. Gibt False zurück, wenn die Eigenschaft nicht gefunden wird oder wenn ein Argument ungültig ist.

Syntax:

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

Parameter:

unoobject: Das zu prüfende Objekt.

propertyname: Die Eigenschaft als Zeichenfolge unter Beachtung der Groß- und Kleinschreibung

Beispiel:

In Basic


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

In Python


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

OpenURLInBrowser

Öffnet eine URL im Standardbrowser.

Syntax:

session.OpenURLInBrowser(url: str)

Parameter:

url: Die zu öffnende URL.

Beispiel:


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


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

RunApplication

Führt einen beliebigen Systembefehl aus und gibt True zurück, wenn er erfolgreich gestartet wurde.

Syntax:

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

Parameter:

command: Der auszuführende Befehl. Dies kann eine ausführbare Datei oder ein Dokument sein, das bei einer Anwendung registriert ist, sodass das System weiß, welche Anwendung für dieses Dokument zu starten ist. Der Befehl muss in der aktuellen Notation SF_FileSystem.FileNaming ausgedrückt werden.

parameters: Eine Liste von durch Leerzeichen getrennte Parameter als einzelne Zeichenfolge. Die Methode validiert die angegebenen Parameter nicht, sondern übergibt sie nur an den angegebenen Befehl.

Beispiel:

In Basic


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

In Python


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

SendMail

Senden einer Nachricht – mit optionalen Anhängen – an Empfänger vom E-Mail-Client des Benutzers. Die Nachricht kann vom Benutzer vor dem Senden bearbeitet oder alternativ sofort gesendet werden.

Syntax:

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

Parameter:

recipient: Eine E-Mail-Adresse (der Empfänger unter „An“).

cc: Eine durch Kommata getrennte Liste mit E-Mail-Adressen (die Empfänger unter „Kopie“).

bcc: Eine durch Kommata getrennte Liste mit E-Mail-Adressen (die Empfänger unter „Blindkopie“).

subject: Der Betreff der Nachricht.

body: Der Inhalt der Nachricht als unformatierter Text.

filenames: Eine durch Kommata getrennte Liste von Dateinamen. Jeder Dateiname muss die Notation SF_FileSystem.FileNaming berücksichtigen.

editmessage: Wenn True (Standard), kann die Nachricht bearbeitet werden, bevor sie gesendet wird.

Beispiel:

In Basic


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

In Python


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

SetPDFExportOptions

Ändert die PDF-Exporteinstellungen, die im Dialog PDF-Optionen definiert sind, auf den Sie zugreifen können, indem Sie Datei – Exportieren als – Als PDF exportieren… wählen.

Das Aufrufen dieser Methode ändert die tatsächlichen Werte, die im Dialog PDF-Optionen eingestellt sind, die von der Methode ExportAsPDF des Dienstes Document verwendet werden.

Diese Methode gibt True zurück, wenn sie erfolgreich war.

Lesen Sie die Wiki-Seite PDF-Export, um mehr über alle verfügbaren Optionen zu erfahren.

Syntax:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parameter:

pdfoptions: Objekt Dictionary, das die zu ändernden PDF-Exporteinstellungen definiert. Jedes Schlüssel-Wert-Paar stellt eine Exportoption und den Wert dar, der im Dialog festgelegt wird.

Beispiel:

In Basic

Das folgende Beispiel ändert die maximale Bildauflösung auf 150 dpi und exportiert das aktuelle Dokument als PDF-Datei.


    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)

Diese Methode ist nur für Basic-Skripte verfügbar.

UnoMethods

Gibt eine Liste der Methoden zurück, die von einem UNO-Objekt aufgerufen werden können. Die Liste ist eine nullbasierte Matrix von Zeichenfolgen und kann leer sein.

Syntax:

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

Parameter:

unoobject: Das zu prüfende Objekt.

Beispiel:

In 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

In Python


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

UnoProperties

Gibt eine Liste der Eigenschaften eines UNO-Objekts zurück. Die Liste ist eine nullbasierte Matrix mit Zeichenfolgen und kann leer sein.

Syntax:

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

Parameter:

unoobject: Das zu prüfende Objekt.

Beispiel:

In Basic


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

In 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

Identifiziert den Typ eines UNO-Objekts als Zeichenfolge.

Syntax:

session.UnoObjectType(unoobject: uno): str

Parameter:

unoobject: Das zu identifizierende Objekt.

Beispiel:

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

In 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

Holt einige Webinhalte von einer URI.

Syntax:

session.WebService(uri: str): str

Parameter:

uri: URI-Adresse des Webservices.

Beispiel:

In Basic


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

In Python


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

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Funktion Array

Calc-Funktionen in Macros verwenden

Python-Skripte aus Basic aufrufen

Dienst ScriptForge.Basic

Dienst ScriptForge.FileSystem