Storitev ScriptForge.Session

Storitev Session obsega različne splošne metode glede:

• okolja nameščanja ali izvajanja,

• vpogleda v delovanje UNO in

• priklica zunanjih skriptov ali programov.

Priklic storitve

Pred uporabo storitve Session je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService

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

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

Konstante

Sledi seznam konstant, ki so na voljo za poenostavitev označevanja knjižnice, ki vsebuje skript v jeziku Basic ali Python, ki ga želite priklicati. Uporabite jih kot session.CONSTANT.

Metode Execute... v storitvi Session se vedejo na sledeč način:
argumenti so podani z vrednostjo. Spremembe argumentov, ki jih izvede klicana funkcija, niso vrnjene skriptu, ki kliče funkcijo.
Klicnemu skriptu je vrnjena enojna vrednost ali polje vrednosti.

ExecuteBasicScript

Izvede skript BASIC s podanim mestom in imenom ter prejme rezultat, če obstaja.

Če skript ne vrne ničesar, kar je primer pri procedurah, definiranih s Sub, je vrnjena vrednost Empty.

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

scope: niz, ki določa, kje je skript shranjen. Lahko je »document« (konstanta session.SCRIPTISEMBEDDED) ali »application« (konstanta session.SCRIPTISAPPLICATION).

script: niz, ki določa skript, ki bo klican, v obliki »knjižnica.modul.metoda«, kot niz, ki razlikuje med velikimi in malimi črkami.

• Knjižnica se po potrebi naloži v pomnilnik.

• Modul ne sme biti razredni modul.

• Ta metoda je lahko Sub (podprogram) ali Function (funkcija).

args: argumenti, podani klicanemu skriptu.

Poglejmo naslednjo funkcijo Basic z imenom DummyFunction, ki je shranjena v »Moji makri« v knjižnici »Standard« v modulu »Module1«.

Funkcija enostavno vzame dve celoštevilski vrednosti v1 in v2 ter vrne vsoto vseh vrednosti, začenši z v1 in s koncem pri 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

Spodnji primer prikazuje klic DummyFunction iz skriptov v jezikih Basic in Python.

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

Izvede funkcijo Calc z njenim angleškim imenom in s podanimi argumenti.
Če so argumenti polja, se funkcija izvede kot formula za polja.

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

calcfunction: angleško ime funkcije programa Calc, ki naj bo izvedena.

arg0, arg1, ...: argumenti za klicano funkcijo Calc. Vsak argument mora biti niz, številska vrednost ali polje kombinacije le-teh.

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)
' Povzroči napako.

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

Izvede skript Python s podanim mestom in imenom ter prejme rezultat, če obstaja. Rezultat je lahko posamezna vrednost ali polje vrednosti.

Če skripta ni mogoče najti ali ne vrne ničesar, je vrnjena vrednost Empty.

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

scope: ena od možnih konstant, navedenih zgoraj. Privzeta vrednost je session.SCRIPTISSHARED.

script: »knjižnica/modul.py$metoda«, »modul.py$metoda« ali »mojaRazširitev.oxt|mojSkript|modul.py$metoda« kot niz, razlikuje med velikimi in malimi črkami.

• library: pot mape za modul Python.

• mojSkript: mapa, ki vsebuje modul Python.

• modul.py: modul Python.

• method: funkcija Python.

args: argumenti, podani klicanemu skriptu.

Poglejmo funkcijo Python odd_integers, definirano spodaj, ki ustvari seznam z lihimi celoštevilskimi vrednostmi med v1 in v2. Recimo, da je ta funkcija shranjena v datoteki, imenovani my_macros.py v vaši uporabniški mapi s skripti.

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

Preberite stran pomoči Organiziranje in hramba skriptov Python, da izveste več, kje lahko hranite skripte Python.

Naslednji primeri prikazujejo klic funkcije odd_integers iz skriptov Basic in Python.

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

Vrne trenutne nastavitve izvoza v PDF, določene v pogovornem oknu Možnosti PDF, do katerih lahko dostopate z menijskim ukazom Datoteka – Izvozi kot – Izvozi v PDF.

Izvozne možnosti, določene s pogovornim oknom Možnosti PDF, se hranijo za kasnejšo rabo. Tako GetPDFExportOptions vrne trenutno določene nastavitve. Poleg tega uporabite SetPDFExportOptions, da spremenite trenutne izvozne možnosti za PDF.

Ta metoda vrne predmet Dictionary, v katerem vsak ključ predstavlja izvozne možnosti in ustrezne vrednosti, ki so trenutne nastavitve za izvoz v PDF.

Preberite wiki-stran o izvozu v PDF (v angl.), da izveste več o vseh razpoložljivih možnosti.

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

Ta metoda je na voljo samo za skripte Basic.

HasUnoMethod

Vrne True, če UNO-predmet vsebuje dano metodo. Vrne False, če metode ni mogoče najti ali ko argument ni veljaven.

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

unoobject: predmet za proučevanje.

methodname: ime metode; razlikuje med velikimi in malimi črkami.

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

Vrne True, če ima UNO-predmet dano lastnost. Vrne False, če lastnosti ni mogoče najte ali če argument ni veljaven.

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

unoobject: predmet za proučevanje.

propertyname: ime lastnosti; razlikuje med velikimi in malimi črkami.

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

Odpre naslov URL (angl. Uniform Resource Locator) v privzetem brskalniku.

session.OpenURLInBrowser(url: str)

url: URL, ki ga želite odpreti.

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

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

RunApplication

Izvede arbitrarni sistemski ukaz in vrne True, če se je uspešno zagnal.

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

command: ukaz, ki ga želite izvesti. To je lahko izvršna datoteka ali dokument, registriran s programom, tako da sistem ve, kateri program naj zažene za tovrstni dokument. Ukaz mora biti izražen v trenutni notaciji SF_FileSystem.FileNaming.

parameters: seznam parametrov, ločenih s presledki, podanih kot en sam niz. Metoda ne preveri veljavnosti podanih parametrov, temveč ji le posreduje navedenemu ukazu.

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

Pošlje sporočilo – z neobveznimi priponkami – prejemnikom iz e-poštnega odjemalca uporabnika. Sporočilo lahko uporabnik pred pošiljanjem uredi ali pa je poslano neposredno.

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

recipient: e-poštni naslov prejemnika (v polju »Za«).

cc: z vejico ločen seznam e-poštnih naslovov prejemnikov (v polju »Kp«, kopija).

bcc: z vejico ločen seznam e-poštnih naslovov prejemnikov (v polju »Skp«, skrita kopija).

subject: glava sporočila oz. zadeva.

body: vsebina sporočila kot neoblikovano besedilo.

filenames: z vejicami ločen seznam imen datotek. Vsako ime datoteke mora slediti notacijiSF_FileSystem.FileNaming.

editmessage: če je True (privzeta vrednost), lahko sporočilo pred pošiljanjem urejate.

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

Spremeni trenutne nastavitve izvoza v PDF, določene v pogovornem oknu Možnosti PDF, do katerih lahko dostopate z menijskim ukazom Datoteka – Izvozi kot – Izvozi v PDF.

S klicem te metode spremenite dejanske vrednosti, nastavljene v pogovornem oknu Možnosti PDF, ki jih uporablja metoda ExportAsPDF storitve Document.

Ta metoda vrne True, če uspe.

Preberite wiki-stran o izvozu v PDF (v angl.), da izveste več o vseh razpoložljivih možnosti.

session.SetPDFExportOptions(pdfoptions: obj): bool

pdfoptions: predmet Dictionary, ki določa nastavitve izvoza v PDF, ki naj se spremenijo. Vsak par ključ-vrednost predstavlja izvozno možnost in vrednost, ki bo nastavljena v pogovornem oknu.

Naslednji primer spremeni največjo ločljivost slik na 150 DPI in izvozi trenutni dokument v datoteko PDF.

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)

Ta metoda je na voljo samo za skripte Basic.

UnoMethods

Vrne seznam metod, ki jih je mogoče klicati iz predmeta UNO. Seznam je ničelno polje nizov in je lahko prazno.

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

unoobject: predmet za proučevanje.

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

Vrne seznam lastnosti predmeta UNO. Seznam je ničelno polje nizov in je lahko prazno.

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

unoobject: predmet za proučevanje.

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

Identificira vrsto predmeta UNO kot niz.

session.UnoObjectType(unoobject: uno): str

unoobject: predmet, ki ga je potrebno identificirati.

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

Pridobi spletno vsebino z naslova URI.

session.WebService(uri: str): str

uri: besedilo URI spletne storitve.

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

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.