Service ScriptForge.Session

De service Session verzamelt verschillende algemene methoden over:

• de installatie- of uitvoeringsomgeving

• UNO-introspectie

• het aanroepen van externe scripts of programma's

Service aanroep

Voordat de service Session gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

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

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

Constanten

Hieronder vindt u een lijst met constanten die beschikbaar zijn om de aanduiding van de bibliotheek met een aan te roepen Basic- of Python-script te vergemakkelijken. Gebruik ze als session.CONSTANT.

Execute...-methoden in de service Session gedragen zich als volgt:
Argumenten worden doorgegeven op basis van waarde. Wijzigingen die door de aangeroepen functie in de argumenten zijn aangebracht, werken hun waarden niet bij in het aanroepende script.
Een enkele waarde of een reeks waarden wordt teruggestuurd naar het aanroepende script.

ExecuteBasicScript

Voer het BASIC-script uit met zijn naam en locatie, en haal het eventuele resultaat op.

Als het script niets retourneert, wat het geval is bij procedures die zijn gedefinieerd met Sub, is de geretourneerde waarde Empty.

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

scope: Tekenreeks die aangeeft waar het script wordt opgeslagen. Het kan "document" (constant session.SCRIPTISEMBEDDED) of "application" (constant session.SCRIPTISAPPLICATION) zijn.

script: Tekenreeks die het aan te roepen script specificeert in de indeling "library.module.method" als hoofdlettergevoelige tekenreeks.

• De bibliotheek wordt indien nodig in het geheugen geladen.

• De module mag geen klassenmodule zijn.

• De methode kan een Sub of een Function zijn.

args: De argumenten die moeten worden doorgegeven aan het aangeroepen script.

Overweeg de volgende basisfunctie met de naam DummyFunction die is opgeslagen in "MijnMacro's" in de bibliotheek "Standard" in een module met de naam "Module1".

De functie neemt eenvoudig twee gehele waarden v1 en v2 en retourneert de som van alle waarden die beginnen in v1 en eindigen op 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

De onderstaande voorbeelden laten zien hoe u DummyFunction aanroept vanuit Basic- en Python-scripts.

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

Voer een Calc-functie uit met de Engelse naam en op basis van de gegeven argumenten.
Als de argumenten matrixen zijn, wordt de functie uitgevoerd als een matrixformule.

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

calcfunction: De naam van de aan te roepen Calc-functie, in het Engels.

args: De argumenten die moeten worden doorgegeven aan de aangeroepen Calc-functie. Elk argument moet een tekenreeks, een numerieke waarde of een reeks matrixen zijn die deze typen combineren.

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)
' Genereert een fout.

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

Voer het Python-script uit gezien de locatie en naam, haal het eventuele resultaat op. Het resultaat kan een enkele waarde of een reeks waarden zijn.

Als het script niet wordt gevonden, of als het niets retourneert, is de geretourneerde waarde Empty.

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

scope: Een van de vermelde toepasselijke constanten hierboven. De standaardwaarde is session.SCRIPTISSHARED.

script: Ofwel "library/module.py$method" of "module.py$method" of "myExtension.oxt|myScript|module.py$method" als hoofdlettergevoelige tekenreeks.

• library: Het mappad naar de Python-module.

• myScript: De map met de Python-module

• module.py: De Python-module

• method: De Python-functie.

args: De argumenten die moeten worden doorgegeven aan het aangeroepen script.

Overweeg de hieronder gedefinieerde Python-functie odd_integers die een lijst maakt met oneven integere waarden tussen v1 en v2. Stel dat deze functie is opgeslagen in een bestand met de naam my_macros.py in de map met gebruikersscripts.

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

Lees de helppagina Python Scripts Organisatie en Locatie voor meer informatie over waar Python-scripts kunnen worden opgeslagen.

De volgende voorbeelden laten zien hoe u de functie odd_integers aanroept vanuit Basic- en Python-scripts.

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

Retourneert de huidige PDF-exportinstellingen die zijn gedefinieerd in het dialoogvenster PDF-opties, dat toegankelijk is door Bestand - Exporteren als - Exporteren als PDF te kiezen.

Exportopties die zijn ingesteld met het dialoogvenster PDF-opties worden bewaard voor toekomstig gebruik. Daarom retourneert GetPDFExportOptions de instellingen die momenteel zijn gedefinieerd. Gebruik daarnaast SetPDFExportOptions om de huidige PDF-exportopties te wijzigen.

Deze methode retourneert een Dictionary-object waarin elke sleutel exportopties vertegenwoordigt en de bijbehorende waarden de huidige PDF-exportinstellingen zijn.

Lees de Wiki-pagina the PDF Export voor meer informatie over alle beschikbare opties.

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

Deze methode is alleen beschikbaar voor BASIC-scripts.

HasUnoMethod

Retourneert True als een UNO-object de opgegeven methode bevat. Retourneert False wanneer de methode niet wordt gevonden of wanneer een argument ongeldig is.

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

unoobject: Het te inspecteren object.

methodname: de methode als een hoofdlettergevoelige tekenreeks

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

Retourneert True als een UNO-object de gegeven eigenschap heeft. Retourneert False wanneer de eigenschap niet wordt gevonden of wanneer een argument ongeldig is.

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

unoobject: Het te inspecteren object.

propertyname: de eigenschap als een hoofdlettergevoelige tekenreeks

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

Open een Uniform Resource Locator (URL) in de standaardbrowser.

session.OpenURLInBrowser(url: str)

url: De te openen URL.

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

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

RunApplication

Voert een willekeurige systeemopdracht uit en retourneert True als die succesvol is gestart.

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

command: De uit te voeren opdracht . Dit kan een uitvoerbaar bestand zijn of een document dat bij een toepassing is geregistreerd, zodat het systeem weet welke toepassing voor dat document moet worden gestart. De opdracht moet worden uitgedrukt in de huidige notatie SF_FileSystem.FileNaming.

parameters: Een lijst met door spaties gescheiden parameters als een enkele tekenreeks. De methode valideert de gegeven parameters niet, maar geeft ze alleen door aan de opgegeven opdracht.

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

Stuur een bericht - met optionele bijlagen - naar ontvangers vanuit de e-mailclient van de gebruiker. Het bericht kan door de gebruiker worden bewerkt voordat het wordt verzonden of, als alternatief, onmiddellijk worden verzonden.

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

recipient: Naar e-mailadres (de "Aan"-ontvanger).

cc: Een door komma's gescheiden lijst van e-mailadressen (de ontvangers onder "Kopie").

bcc: Een door komma's gescheiden lijst van e-mailadressen (de ontvangers onder "Blinde kopie").

subject: het onderwerp van het bericht.

body: De inhoud van het bericht als niet-opgemaakte tekst.

filenames: een door komma's gescheiden lijst met bestandsnamen. Elke bestandsnaam moet de notatie SF_FileSystem.FileNaming respecteren.

editmessage: Indien True (standaard), wordt het bericht bewerkt voordat het wordt verzonden.

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

Wijzigt de PDF-exportinstellingen die zijn gedefinieerd in het dialoogvenster PDF-opties, dat toegankelijk is door Bestand - Exporteren als - Exporteren als PDF te kiezen.

Door deze methode aan te roepen, worden de werkelijke waarden gewijzigd die zijn ingesteld in het dialoogvenster PDF-opties, die worden gebruikt door de methode ExportAsPDF van de service Document.

Deze methode retourneert True indien succesvol.

Lees de Wiki-pagina PDF Export voor meer informatie over alle beschikbare opties.

session.SetPDFExportOptions(pdfoptions: obj): bool

pdfoptions: Dictionary object dat de PDF-exportinstellingen definieert die moeten worden gewijzigd. Elk sleutel/waarde-paar vertegenwoordigt een exportoptie en de waarde die in het dialoogvenster wordt ingesteld.

In het volgende voorbeeld wordt de maximale afbeeldingsresolutie gewijzigd in 150 dpi en wordt het huidige document geëxporteerd als een PDF-bestand.

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)

Deze methode is alleen beschikbaar voor BASIC-scripts.

UnoMethods

Retourneert een lijst met de methoden die kunnen worden aangeroepen vanuit een UNO-object. De lijst is een op nul gebaseerde reeks tekenreeksen en kan leeg zijn.

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

unoobject: Het te inspecteren object.

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

Retourneert een lijst met de eigenschappen van een UNO-object. De lijst is een op nul gebaseerde reeks tekenreeksen en kan leeg zijn.

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

unoobject: Het te inspecteren object.

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

Identificeer het type van een UNO-object als een tekenreeks.

session.UnoObjectType(unoobject: uno): str

unoobject: Het te identificeren object.

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

Haal wat webinhoud op uit een URI.

session.WebService(uri: str): str

uri: URI-adres van de webservice.

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

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.