Vsebina

# 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. Ta metoda enakovredno zažene skripte .bat ali skripte lupine. 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.

Podobne teme

Funkcija Array

Raba funkcij programa Calc v makrih

Klicanje skriptov Python iz Basica

Storitev ScriptForge.Basic

Storitev ScriptForge.FileSystem service