Tjenesten ScriptForge.Session

Tjenesten Session samler forskellige generelle metoder:

Kald af tjeneste

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

note

• 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


I Basic

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

    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.

CONSTANT

Værdi

Hvor findes biblioteket?

Anvendelig

SCRIPTISEMBEDDED

"document"

i dokumentet

Basic + Python

SCRIPTISAPPLICATION

"application"

i ethvert delt bibliotek

Basic

SCRIPTISPERSONAL

"user"

in My Macros

Python

SCRIPTISPERSOXT

"user:uno_packages"

i en udvidelse, der installeret til den aktuelle bruger

Python

SCRIPTISSHARED

"share"

in Application Macros

Python

SCRIPTISSHAROXT

"share:uno_packages"

i en udvidelse, der er installeret til alle brugere

Python

SCRIPTISOXT

"uno_packages"

i en udvidelse, selv om installationsparametrene er ukendte

Python


Tjenesten List of Methods in the Session (Liste over metoder i sessionen)

ExecuteBasicScript
ExecuteCalcFunction
ExecutePythonScript
GetPDFExportOptions
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail
SetPDFExportOptions

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

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

Syntaks:

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

Parametre:

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.

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

Eksempel:

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.

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

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

Syntaks:

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

Parametre:

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.

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 en fejl.
  
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

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

LibreOffice Application Programming Interface (API)s rammer for scripts understøtter mellemsproglig udførelse af scripts mellem Python og Basic, eller for den sags skyld med andre understøttede programmeringssprog. Argumenter kan videregives frem og tilbage på tværs af kald, forudsat at de repræsenterer primitive datatyper, som begge sprog genkender, og under den antagelse af scripting-rammerne konverterer dem på passende måde.

Syntaks:

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

Parametre:

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.

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

Eksempel:

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
  
tip

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.

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 de aktuelle PDF-eksportindstillinger, der er defineret i dialogen PDF Indstillinger, som kan tilgås ved at vælge Filer ▸ Eksporter som ▸ Eksporter 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.

tip

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


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

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.

Syntaks:

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

Parametre:

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

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

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

Syntaks:

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

Parametre:

unoobject: Det objekt, der skal inspiceres.

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

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

Ă…bn en Uniform Resource Locator (URL) i standardbrowseren.

Syntaks:

session.OpenURLInBrowser(url: str)

Parametre:

url: Den URL, der skal ĂĄbnes.

Eksempel:


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

Syntaks:

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

Parametre:

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.

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

Syntaks:

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

Parametre:

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.

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

Modificerer de PDF-indstillinger, der er defineret i dialogen PDF-indstillinger, som kan tilgås ved at vælge Filer ▸ Eksporter som ▸ Eksporter 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.

tip

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


Syntaks:

session.SetPDFExportOptions(pdfoptions: obj): bool

Parametre:

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.

Eksempel:

I Basic

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

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.

Syntaks:

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

Parametre:

unoobject: Det objekt, der skal inspiceres.

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 en liste over et UNO-objekts egenskaber. Listen er en nul-baseret matrix af strenge og kan være tom.

Syntaks:

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

Parametre:

unoobject: Det objekt, der skal inspiceres.

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

Identificer et UNO-objekts type som en streng.

Syntaks:

session.UnoObjectType(unoobject: uno): str

Parametre:

unoobject: Det objekt, der skal identificeres.

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 noget webindhold fra en URI.

Syntaks:

session.WebService(uri: str): str

Parametre:

uri: Webtjenestens URI-adresse.

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

Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.


Støt os venligst!