Dienst ScriptForge.Session

Der Dienst Session sammelt verschiedene Allzweckmethoden zu:

Dienstaufruf

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

note

• 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 Extension

Python

SCRIPTISSHARED

"share"

in LibreOffice-Makros

Python

SCRIPTISSHAROXT

"share:uno_packages"

in einer fĂĽr alle Benutzer installierten Extension

Python

SCRIPTISOXT

"uno_packages"

in einer Extension, 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


tip

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ĂĽhrt das Basic-Skript mit seinem Namen und Speicherort aus und ruft 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 angibt, 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 angibt.

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 "„meineExtension.oxt|meinSkript|Modul.py$Methode" als Zeichenfolge unter Beachtung der Groß-/Kleinschreibung.

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
  
tip

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.

tip

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

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.

tip

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

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

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.


Bitte unterstĂĽtzen Sie uns!