Inhoud

# Service ScriptForge.Session

De service Session verzamelt verschillende algemene methodes 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 methodes in de service Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

Execute...-methodes 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 waardes niet bij in het aanroepende script.
Een enkele waarde of een reeks waardes 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 waardes v1 en v2 en retourneert de som van alle waardes 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.

De methode retourneert een scalaire waarde (tekenreeks of numeriek) of de matrix van matrixen die door de functieaanroep wordt geretourneerd.

### 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 aan de aangeroepen Calc-functie moeten worden doorgegeven.
Elk argument kan ofwel zijn

- een tekenreeks, een numerieke waarde, een datum of een booleaans teken

- een 1D-matrix, een 2D-matrix of een matrix van matrixen die bovenstaande gegevenstypes combineert

- een com.sun.star.table.XCellRange UNO-object

### 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
        ' --------
        tabel1 = Array("Symbol", "H", "He", "Li")
        tabel2 = Array("AtomicNumber", 1.0, 2.0, 3.0)
        tabel3 = Array("Mass", 1.008, 4.0026, 6.94)
        tabel = Array(tabel1, tabel2, tabel3)  ' matrix van matrixen
        zoeken = Array("Symbol", "AtomicNumber", "Mass")
        resultaat = session.ExecuteCalcFunction("X.ZOEKEN", "Mass", zoeken, tabel)
        MsgBox resultaat(0)(3)  ' 6.94

##### 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) # Error
        # --------
        table = ( ("Symbol", "H", "He", "Li"),
                  ("AtomicNumber", 1.0, 2.0, 3.0),
                  ("Mass", 1.008, 4.0026, 6.94) )
        search = ("Symbol", "AtomicNumber", "Mass")
        result = session.ExecuteCalcFunction("XLOOKUP", "Mass", search, table)
        basic = CreateScriptService('Basic')
        basic.MsgBox(result[0][3]) # 6.94

## 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 waardes 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: Eén 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 waardes 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 naar - Naar PDF exporteren 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 waardes 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 opdracht die moet worden uitgevoerd. Dit kan een uitvoerbaar bestand zijn of een document dat is geregistreerd bij een toepassing, zodat het systeem weet welke toepassing moet worden gestart voor dat document. Deze methode start ook .bat- of shellscripts. De opdracht moet worden uitgedrukt in de huidige SF_FileSystem.FileNaming-notatie.

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 naar - Naar PDF exporteren te kiezen.

Door deze methode aan te roepen, worden de werkelijke waardes 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 methodes 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.

Verwante onderwerpen

Functie Matrix

Calc-functies in macro's gebruiken

Python-scripts vanuit BASIC aanroepen

ScriptForge.Basic service

ScriptForge.FileSystem-service

Help ons, alstublieft!