Tenesta ScriptForge.Session

Tenesta Session samlar ulike generelle metodar:

installasjons- eller utførings-miljøet
UNO-introspeksjon
oppkall av eksterne skript eller program

Oppkall av tenester

Før du brukar tenesta Session, må biblioteket ScriptForge vera lasta inn eller importert:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

I Basic


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

I Python


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

Konstantar

Nedanfor er ei liste over tilgjengelege konstantar for å finna ut kva for eit bibliotek som inneheld eit Basic- eller Python-skript som skal kallast opp. Bruk dette som session.CONSTANT.

CONSTANT	Verdi	Kvar finn eg biblioteket?	Tilgjengeleg
SCRIPTISEMBEDDED	"document"	i dokumentet	Basic + Python
SCRIPTISAPPLICATION	"application"	i eit delt bibliotek	Basic
SCRIPTISPERSONAL	"user"	i Mine makroar	Python
SCRIPTISPERSOXT	"user:uno_packages"	i ei utviding installert for den gjeldande brukaren	Python
SCRIPTISSHARED	"share"	i programmakroar	Python
SCRIPTISSHAROXT	"share:uno_packages"	i ei utviding installert for alle brukarane	Python
SCRIPTISOXT	"uno_packages"	i ei utviding sjølv om installasjonsparametera er ukjende	Python

Liste over metodar i tenesta Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod	HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions	UnoMethods UnoProperties UnoObjectType WebService

Metodane Execute... i tenesta Session fungerer slik:
Argumenta vert sende vidare som ein verdi. Endringar av argumenta gjort av den oppkallande funksjonen vil ikkje oppdatera verdiane i det skriptet som vert kalla opp.
Det vert returnert ein enkelt verdi eller ei matrise av verdiar til det oppkallande skriptet.

ExecuteBasicScript

Køyrer BASIC-skriptet med namn og plassering, og hentar eventuelt resultatet.

Viss skriptet ikkje returnerer noko, noko som skjer med prosedyrar som er definerte med Sub, er returverdien Empty.

Syntaks:

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

Parametrar:

scope: Streng som seier kor skriptet er lagra. Det kan vera anten "document" (konstant session.SCRIPTISEMBEDDED) eller "application" (konstant session.SCRIPTISAPPLICATION).

script: Streng som spesifiserer skriptet som skal kallast opp i formatet "library.module.method" som ein streng som skil mellom store og små bokstavar.

Biblioteket vert lasta inn i minnet om nødvendig.
Modulen må ikkje vera ein klasse-modul.
Metoden kan vera ein Sub eller ein Function

args: Argumenta som skal sendast til det oppkalla skriptet.

Eksempel:

Sjå på Basic-funksjonen med namnet DummyFunction, som er lagra i "Mine makroar" i "Standard"-biblioteket inne i ein modul kalla "Module1".

Funksjonen tek heilt enkelt to heiltals-verdiarv1 og v2 og returnerer summen av alle verdiane som byrjar med v1 og sluttar 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

Eksempla nedanfor viser korleis DummyFunction vert kalla opp inne frå Basic- og Python-skript.

I 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

I 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

Utfør ein Calc-funksjon ved å bruka det engelske namnet på han og basert på dei gjevne argumenta.
Viss argumenta er matriser, vert funksjonen utført som ein matriseformel.

Syntaks:

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

Parametrar:

calcfunction: Namnet på den Calc-funksjonen som skal kallast opp på engelsk.

args: Argumenta som skal overførast til den kalla Calc-funksjonen. Kvart argument må anten vera ein streng, ein numerisk verdi eller ei matrise av matriser som kombinerer desse typane.

Eksempel:

I 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)
    ' Genererer ein feil.

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

ExecutePythonScript

Køyrer Python-skriptet frå plasseringa og namnet og hentar eventuelt resultatet. Resultatet kan vera éin enkelt verdi eller ei matrise med verdiar.

Viss skriptet ikkje vert funne eller ikkje returnerer noko, vert det returnert verdien Empty.

Skriptnettverket LibreOffice Application Programming Interface (API) har støtte for å køyra blanda skript mellom Python og Basic, eller andre programmeringsspråk for den saks skuld. Såleis kan argument sendast mellom språka dersom dei er såkalla primitive datatypar som begge språka forstår og at dei vert konverterte korrekt.

Syntaks:

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

Parametrar:

scope: Ein av dei tilgjengelege konstantane som er oppført over. Standardverdien er session.SCRIPTISSHARED.

script: Anten "library/module.py$method", "module.py$method" eller "myExtension.oxt|myScript|module.py$method" som ein streng som skil mellom store og små bokstavar.

library: Mappestien til Python-modulen.
myScript: Mappa som inneheld Python-modulen.
module.py: Python-modulen.
metode: Python-funksjonen.

args: Argumenta som skal sendast til det oppkalla skriptet.

Eksempel:

Sjå på Python-funksjonen odd_integers definert nedanfor, som lagar ei liste over odde heiltalsverdiar mellom v1 og v2. Gå ut frå at denne funksjonen er lagra i ei fil med namnet my_macros.py i brukarskriptmappa.


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

Les hjelpsida Organisering og plassering av Python-skript for å læra meir om kvar Python-skripta kan lagrast.

Dei neste eksempla viser korleis funksjonen odd_integers vert kalla opp av Basic- og Python-skript.

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

I Python


    session = CreateScriptService("Session")
    script = "my_macros.py$odd_integers"
    result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)
    bas.MsgBox(repr(result))

GetPDFExportOptions

Returnerer dei gjeldande innstillingane for PDF-eksport definerte i dialogvindauget PDF Innstillingar, som du har tilgang til frå Fil → Eksporter som → Eksporter som PDF.

Eksportinnstillingane som er sette i dialogvindauget PDF-innstillingar vert oppretthalde for framtidig bruk. Difor returnerer GetPDFExportOptions dei gjeldande innstillingane. Bruk også SetPDFExportOptions for å endra dei gjeldande PDF-eksportinnstillingane.

Denne metoden returnerer eit Dictionary-objekt der kvar nøkkel representerer innstillingar der dei samsvarande verdiane er dei gjeldande eksportinnstillingane.

Du finn meir om dei tilgjengelege innstillingane i PDF Export wiki page.

Syntaks:

session.GetPDFExportOptions(): obj

Eksempel:

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

Denne metoden er tilgjengeleg berre for Basic-skript.

HasUnoMethod

Returnerer Sann viss eit UNO-objekt inneheld den gjevne metoden. Returnerer Usann når metoden ikkje vart funnen eller når eit argument er ugyldig.

Syntaks:

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

Parametrar:

unoobject: Objektet som skal kontrollerast.

methodname: metoden som ein streng som skil mellom store og små bokstavar

Eksempel:

I Basic


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

I Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoMethod(a, "callFunction")
    bas.MsgBox(result) # True

HasUnoProperty

Returnerer Sann viss eit UNO-objekt har den gjevne metoden. Returnerer Usann når metoden ikkje vart funnen eller når eit argument er ugyldig.

Syntaks:

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

Parametrar:

unoobject: Objektet som skal kontrollerast.

propertyname: metoden som ein streng som skil mellom store og små bokstavar

Eksempel:

I Basic


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

I Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoProperty(a, "Wildcards")
    bas.MsgBox(result) # True

OpenURLInBrowser

Opnar ein Uniform Resource Locator (URL) i standard nettlesar.

Syntaks:

session.OpenURLInBrowser(url: str)

Parametrar:

url: Adressa som skal opnast.

Eksempel:


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


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

RunApplication

Utfører ein arbitrær system-kommando og returnerer Sann viss det lukkast å starta han.

Syntaks:

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

Parametrar:

command: Kommandoen som skal køyrast. Dette kan vera ei køyrbar fil eller eit dokument som er registrert i eit program, slik at systemet veit kva for program som skal startast for det dokumentet. Kommandoen må vera i den gjeldande SF_FileSystem.FileNaming-notasjonen.

parameters: Ei liste over parameterar, skilde med mellomrom, som ein enkelt streng. Metoden validerer ikkje dei gjevne parametera, men sender dei berre vidare til den gjevne kommandoen.

Eksempel:

I Basic


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

I Python


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

SendMail

Send ei melding – med valfrie vedlegg – til mottakarane frå brukaren sin e-postklient. Meldinga kan redigerast av brukaren før ho vert sendt, eller sendast straks.

Syntaks:

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

Parametrar:

recipient: Ei e-postadresse (mottakaren «Til»).

cc: Ei komma-separert liste over e-postadresser (mottakarane av «cc» (blåpapirkopi)).

cc: Ei komma-separert liste over e-postadresser (mottakarane av «bcc» (blind blåpapirkopi)).

subject: overskrifta i meldinga (Emne).

body: Innhaldet i meldinga som ein uformatert tekst.

filenames: ei komma-separert liste over filnamn. Kvart filnamn må fylla krava i SF_FileSystem.FileNaming-notasjonen.

editmessage: Når Sann (standard), er meldinga redigert før ho vart sendt.

Eksempel:

I Basic


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

I Python


    session.SendMail("someone@example.com",
                     cc="john@other.fr, mary@other.be"
                     filenames=r"C:\myFile1.txt, C:\myFile2.txt")

SetPDFExportOptions

Endrar innstillingane for PDF-eksport definerte i dialogvindauget PDF Options, som du har tilgang til frå Fil → Eksporter som → Eksporter som PDF.

Oppkall av denne metoden endrar dei aktuelle verdiane som er sette i dialogvindauget PDF-innstillingar, som vert brukt av metoden ExportAsPDF frå tenesta Document.

Denne metoden returnerer Sann viss han lukkast.

Du finn meir om dei tilgjengelege innstillingane i PDF Export wiki page.

Syntaks:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parametrar:

pdfoptions: Objektet Dictionary definerer PDF-eksportindstillingane som skal endrast. Kvart nøkkelverdipar representerer ei eksportinnstilling og den verdien som skal setjast i dialogvindauget.

Eksempel:

I Basic

Eksempelet nedanfor endrar den maksimale biletoppløysninga til 150 dpi og eksporterer det gjeldande dokumentet som ei 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 metoden er tilgjengeleg berre for Basic-skript.

UnoMethods

Returnerer ei liste over metodar som kan kallast opp frå eit UNO-objekt. Lista er ei null-basert matrise av strengar, og kan vera tom.

Syntaks:

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

Parametrar:

unoobject: Objektet som skal kontrollerast.

Eksempel:

I 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

I Python


    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    methods = session.UnoMethods(a)
    msg = "\n".join(methods)
    bas.MsgBox(msg)

UnoProperties

Returnerer ei liste over eigenskapar til eit UNO-objekt. Lista er ei null-basert matrise av strengar, og kan vera tom.

Syntaks:

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

Parametrar:

unoobject: Objektet som skal kontrollerast.

Eksempel:

I Basic


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

I 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

Identifiserer typen til eit UNO-objekt som ein streng.

Syntaks:

session.UnoObjectType(unoobject: uno): str

Parametrar:

unoobject: Objektet som skal identifiserast.

Eksempel:

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

I 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

Hent noko nett-innhald frå ein URI.

Syntaks:

session.WebService(uri: str): str

Parametrar:

uri: URI-adressa til nettenesta.

Eksempel:

I Basic


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

I Python


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

Alle ScriptForge Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Array-funksjonen

Bruka Calc-funksjonar i makroar

Oppkall av Python-skript frå Basic

Tenesta ScriptForge.Basic

Tenesta ScriptForge.FileSystem