Inhalte

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

Verwandte Themen

Funktion Array

Calc-Funktionen in Macros verwenden

Python-Skripte aus Basic aufrufen

Dienst ScriptForge.Basic

Dienst ScriptForge.FileSystem