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

In BASIC


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

In Python


    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.

CONSTANT	Waarde	Waar vind je de bibliotheek?	Toepasbaar
SCRIPTISEMBEDDED	"document"	in het document	Basic + Python
SCRIPTISAPPLICATION	"application"	in een gedeelde bibliotheek	Basic
SCRIPTISPERSONAL	"user"	in Mijn macro's	Python
SCRIPTISPERSOXT	"user:uno_packages"	in een extensie geïnstalleerd voor de huidige gebruiker	Python
SCRIPTISSHARED	"share"	in Toepassingsmacro's	Python
SCRIPTISSHAROXT	"share:uno_packages"	in een extensie geïnstalleerd voor alle gebruikers	Python
SCRIPTISOXT	"uno_packages"	in een extensie maar de installatieparameters zijn onbekend	Python

Lijst met methoden in de service Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod	HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions	UnoMethods UnoProperties UnoObjectType WebService

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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.

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

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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

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

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.

De LibreOffice Application Programming Interface (API) Scripting Framework ondersteunt uitvoering van scripts tussen Python en Basic of andere ondersteunde programmeertalen. Argumenten kunnen worden teruggegeven en doorgegeven bij aanroepen, als die tenminste van een data-type zijn dat door beide talen wordt ondersteund en aannemende dat het Scripting Framework ze goed converteert.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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.

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

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.

Syntaxis:

session.GetPDFExportOptions(): obj

Voorbeeld:

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

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.

Syntaxis:

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

Parameters:

unoobject: Het te inspecteren object.

methodname: de methode als een hoofdlettergevoelige tekenreeks

Voorbeeld:

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

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

Syntaxis:

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

Parameters:

unoobject: Het te inspecteren object.

propertyname: de eigenschap als een hoofdlettergevoelige tekenreeks

Voorbeeld:

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

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

Syntaxis:

session.OpenURLInBrowser(url: str)

Parameters:

url: De te openen URL.

Voorbeeld:


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

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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

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.

Syntaxis:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parameters:

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.

Voorbeeld:

In BASIC

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.

Syntaxis:

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

Parameters:

unoobject: Het te inspecteren object.

Voorbeeld:

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

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

Syntaxis:

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

Parameters:

unoobject: Het te inspecteren object.

Voorbeeld:

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

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

Syntaxis:

session.UnoObjectType(unoobject: uno): str

Parameters:

unoobject: Het te identificeren object.

Voorbeeld:

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

Haal wat webinhoud op uit een URI.

Syntaxis:

session.WebService(uri: str): str

Parameters:

uri: URI-adres van de webservice.

Voorbeeld:

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-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Functie Matrix

Calc-functies in macro's gebruiken

Python-scripts vanuit BASIC aanroepen

ScriptForge.Basic service

ScriptForge.FileSystem-service