Tjenesten ScriptForge.Session

Tjenesten Session samler forskellige generelle metoder:

• installations- eller udførelses-miljøet

• UNO-introspektion

• kald af eksterne skripts eller programmer

Kald af tjeneste

Før brug af tjenesten Session skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

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

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

Konstanter

Herunder er der en liste over tilgængelige konstanter, der letter udpegningen af det bibliotek, der indeholder et Basicc- eller Python-script, der skal påkaldes. Brug dem som session.CONSTANT.

Metoderne Execute... (udfør...) i tjenesten Session har denne adfærd:
Argumenter videregives som værdi. Ændringer af argumenterne, foretaget af den kaldte funktion, opdaterer ikke deres værdier i det script, der kalder.
Der returneres en enkelt værdi eller en matrix af værdier til det script, der kalder.

ExecuteBasicScript

Execute the BASIC script given its name and location, and fetch its result, if any.

Hvis scriptet intet returnerer, hvilket er tilfældet med procedurer, der er defineret med Sub, er returværdien Empty (tom).

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

scope (anvendelse): Streng, der angiver, hvor scriptet er lagtet. Det kan være enten "document" (konstant session.SCRIPTISEMBEDDED) eller "application" (konstant session.SCRIPTISAPPLICATION).

script: Streng, der angiver det script, der skal kaldes i formatet "library.module.method" som en streng med Stort-og-småt.

• Biblioteket indlæses i hukommelsen, om nødvendigt.

• Modulet må ikke være et klasse-modul.

• Metoden kan være en Sub eller en Function

args: De argumenter, der skal videregives til det kaldte script.

Betragt Basic-funktionen ved navn DummyFunction, der er lagret i "Mine makroer" i"Standard"-biblioteket inde i et modul kaldet "Module1".

Funktionen tager helt enkelt to heltals-værdierv1 og v2 og returnerer summen af alle værdier begyndende med v1 og sluttende med 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

Eksemplerne herunder viser, hvordan DummyFunction (attrap_funktion) kaldes inde fra Basic- og 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

Udfør en Calc-funktion med dens engelske navn og baseret på de givne argumenter.
Hvis argumenterne er matrixer, udføres funktionen som en array formula (matrixformel).

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

calcfunction: Navnet på den Calc-funktion, der skal kaldes, på engelsk.

args: De argumenter, der skal videregives til den kaldte Calc-funktion. Hver argument skal være enten en streng, en numerisk værdi eller et matrix af matrixer, der kombinerer disse typer.

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)
' Genererer en fejl.

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

Udfør Python-scriptet givet dets placering og navn, hent dets resultat, om noget. Resultatet kan være en enkelt værdi eller et matrix af værdier.

Hvis scriptet ikke bliver fundet, eller hvis det intet returnerer, er den returnerede værdi Empty (tom).

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

scope: One of the applicable constants listed above. The default value is session.SCRIPTISSHARED.

script: Enten "library/module.py$method" eller "module.py$method" eller "myExtension.oxt|myScript|module.py$method" som en streng med Stort-og-småt.

• library (bibliotek): Mappestien til Python-modulet.

• myScript (mit script): Den mappe, der indeholder Python-modulet.

• module.py: Python-modulet.

• metode: Python-funktionen.

args: De argumenter, der skal videresendes til det kaldte script.

Betragt Python-funktionen odd_integers (ulige_heltal), defineret herunder, der opretter en liste med ulige heltalsværdier mellem v1 og v2. Antag, at denne funktion er lagret i en fil kaldet my_macros.py i din Brugerscript-mappe.

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

Læs hjælpesiden Organisering og placering af Python-scripts for at lære mere om, hvor Python-scripts kan lagres.

De følgende eksempler viser, hvordan funktionen odd_integers (ulige_heltal) kaldes af Basic- og 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

Returnerer de aktuelle PDF-eksportindstillinger, der er defineret i dialogen PDF Indstillinger, som kan tilgås ved at vælge Filer ▸ Eksportér som ▸ Eksportér som PDF.

Eksportindstillinger, der er sat med dialogen PDF Indstillinger beholdes til fremtidigt brug. Derfor returnerer GetPDFExportOptions (hent_PDF-eksportindstillinger) de aktuelt definerede indstillinger. Derudover bruger du SetPDFExportOptions (sæt_PDF-importindstillinger) for at ændre de aktuelle PDF-indstillinger.

Denne metode returnerer et Dictionary (ordbogs)-objekt, hvor hver nøgle repræsenterer indstillinger og de tilsvarende værdier er de aktuelle PDF-eksportindstillinger.

Læs wikisiden PDF-eksport for at få mere at vide om alle indstillinger.

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

Denne metode er kun tilgængelig for Basic-scripts.

HasUnoMethod

Returnerer True, hvis et UNO-objekt indeholder den givne metode. Returnerer False, når metoden ikke bliver fundet eller når et argument er ugyldigt.

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

unoobject (uno-objekt): Det objekt, der skal inspiceres.

methodname (metodenavn): metoden som en streng med Stort-og-småt

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

Returnerer True (sand), hvis et UNO-objekt har en given egenskab. Returnerer False (falsk), når egenskaben ikke er fundet eller når et argument er ugyldigt.

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

unoobject: Det objekt, der skal inspiceres.

propertyname (egenskabsnavn): egenskaben som en streng med Stort-og-småt

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

Åbn en Uniform Resource Locator (URL) i standardbrowseren.

session.OpenURLInBrowser(url: str)

url: Den URL, der skal åbnes.

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

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

RunApplication

Udfører en arbitrær system-kommando og returnerer True (sand), hvis det lykkedes at starte den.

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

command: Den kommando, der skal udføres. Det kan være en eksekverbar fil eller et dokument, som er registreret med et program, så systemet ved, hvilket program, der skal startes til det dokument. Kommandoen skal udtrykkes i den aktuelle SF_FileSystem.FileNaming-notation.

parameters: En liste over mellemrums-delte parametere som en enkelt streng. Metoden validerer ikke de givne parametere, men videregiver dem kun til den angivne kommando.

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

Send en besked – med valgfrie vedhæftninger – til modtagere fra brugerens mailklient. Beskeden kan være kan redigeret af brugeren før afsendelse, eller alternativt blive sendt øjeblikkeligt.

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

recipient (modtager): En E-mailadresse (modtageren "Til").

cc: En komma-separateret liste over e-mailadresser (modtagerne af "gennemslagskopi").

bcc: En komma-separateret liste over e-mailadresser (modtagerne af "blind gennemslagskopi").

subject (emne): meddelelsens overskrift.

body (krop): Indholdet af teksten som en uformateret tekst.

filenames: en komma-separareret liste over filnavne. Hver filnavn skal respektere SF_FileSystem.FileNamings-notationen.

editmessage (rediger meddelelse): Når True (sand)(default), er beskeden redigeret, før den blev sendt.

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

Ændrer de PDF-indstillinger, der er defineret i dialogen PDF-indstillinger, som kan tilgås ved at vælge Filer ▸ Eksportér som ▸ Eksportér som PDF.

Kald af denne metode ændrer de aktuelle værdier, der er sat i dialogen PDF-indstillinger, som bruges af metoden ExportAsPDF (eksporter_som_PDF) fra tjenesten Document.

Denne metode returnerer True (sand), når den lykkes.

Læs wikisiden PDF-eksport for at få mere at vide om alle de tilgængelige indstillinger.

session.SetPDFExportOptions(pdfoptions: obj): bool

pdf-indstillinger: Objektet Dictionary (ordbog), definerer PDF-eksportindstillingerne, der skal ændres. Hvert nøgle-værdi-par repræsenterer en eksportindstilling og den værdi, der skal sættes i dialogen.

Det følgende eksempel ændrer den maksimale billedopløsning til 150 dpi og eksporterer det aktuelle dokument som en PDF-fil.

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)

Denne metode er kun tilgængelig for Basic-scripts.

UnoMethods

Returnerer en liste over metoder, der kan kaldes fra et UNO-objekt. Listen er en nul-baseret matrix af strenge og kan være tom.

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

unoobject: Det objekt, der skal inspiceres.

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

Returnerer en liste over et UNO-objekts egenskaber. Listen er en nul-baseret matrix af strenge og kan være tom.

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

unoobject: Det objekt, der skal inspiceres.

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

Identificer et UNO-objekts type som en streng.

session.UnoObjectType(unoobject: uno): str

unoobject: Det objekt, der skal identificeres.

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

Hent noget webindhold fra en URI.

session.WebService(uri: str): str

uri: Webtjenestens URI-adresse.

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-rutiner eller identifikatorer, der indledes med et understregstegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.