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

V Basicu


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

V Pythonu


    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.

CONSTANT	Vrednost	Kje najdete knjižnico?	Uporabno
SCRIPTISEMBEDDED	"document"	v dokumentu	Basic + Python
SCRIPTISAPPLICATION	"application"	v poljubni knjižnici v skupni rabi,	Basic
SCRIPTISPERSONAL	"user"	v Mojih makrih,	Python
SCRIPTISPERSOXT	"user:uno_packages"	v razširitvi, nameščeni za trenutnega uporabnika,	Python
SCRIPTISSHARED	"share"	v Makri programa,	Python
SCRIPTISSHAROXT	"share:uno_packages"	v razširitvi, nameščeni za vse uporabnike,	Python
SCRIPTISOXT	"uno_packages"	v razširitvi, katere namestitveni parametri niso znani.	Python

Seznam metod v storitvi seje
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod	HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions	UnoMethods UnoProperties UnoObjectType WebService

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.

Skladnja:

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

Parametri:

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.

Primer:

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.

V Basicu


    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

V Pythonu


    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.

Skladnja:

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

Parametri:

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.

Primer:

V Basicu


    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.

V Pythonu


    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.

Ogrodje skriptov vmesnika programiranja LibreOffice API (angl. Application Programming Interface) podpira izvajanje skriptov med Pythonom in Basicom ter drugimi podprtimi programskimi jeziki. Argumente lahko podajate skozi klice, če gre za primitivne vrste podatkov, ki jih prepoznata oba jezika, in če jih ogrodje API ustrezno pretvori.

Skladnja:

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

Parametri:

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.

Primer:

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.

V Basicu


    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)

V Pythonu


    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.

Skladnja:

session.GetPDFExportOptions(): obj

Primer:

V Basicu


    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.

Skladnja:

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

Parametri:

unoobject: predmet za proučevanje.

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

Primer:

V Basicu


    Dim a As Variant
    a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoMethod(a, "callFunction") ' True

V Pythonu


    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.

Skladnja:

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

Parametri:

unoobject: predmet za proučevanje.

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

Primer:

V Basicu


    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoProperty(svc, "Wildcards")

V Pythonu


    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.

Skladnja:

session.OpenURLInBrowser(url: str)

Parametri:

url: URL, ki ga želite odpreti.

Primer:


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

Skladnja:

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

Parametri:

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.

Primer:

V Basicu


    session.RunApplication("Notepad.exe")
    session.RunApplication("C:\myFolder\myDocument.odt")
    session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux

V Pythonu


    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.

Skladnja:

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

Parametri:

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.

Primer:

V Basicu


    session.SendMail("someone@example.com" _
        , Cc := "b@other.fr, c@other.be" _
        , FileNames := "C:\myFile1.txt, C:\myFile2.txt")

V Pythonu


    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.

Skladnja:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parametri:

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.

Primer:

V Basicu

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.

Skladnja:

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

Parametri:

unoobject: predmet za proučevanje.

Primer:

V Basicu


    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

V Pythonu


    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.

Skladnja:

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

Parametri:

unoobject: predmet za proučevanje.

Primer:

V Basicu


    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True

V Pythonu


    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.

Skladnja:

session.UnoObjectType(unoobject: uno): str

Parametri:

unoobject: predmet, ki ga je potrebno identificirati.

Primer:

V Basicu


    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"

V Pythonu


    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.

Skladnja:

session.WebService(uri: str): str

Parametri:

uri: besedilo URI spletne storitve.

Primer:

V Basicu


    session.WebService("wiki.documentfoundation.org/api.php?" _
        & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")

V Pythonu


    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.

Funkcija Array

Raba funkcij programa Calc v makrih

Klicanje skriptov Python iz Basica

Storitev ScriptForge.Basic

Storitev ScriptForge.FileSystem service