ScriptForge.Session-tjenesten

Indhold

# Tjenesten ScriptForge.Session

Tjenesten Session samler forskellige generelle metoder:

- installations- eller udførelses-miljøet

- UNO-introspektion

- kald af eksterne skripts eller programmer

## Kald af tjeneste

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

• 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" | i Mine makroer | Python
SCRIPTISPERSOXT | "user:uno_packages" | i en udvidelse, der installeret til den aktuelle bruger | Python
SCRIPTISSHARED | "share" | i Programmakroer | 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

Liste over metoder i tjenesten Session
ExecuteBasicScript ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

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

Udfør Basic-scriptet ud fra dets navn og placering, og hent eventuelt resultat.

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 gemt. 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 forskel på store og små bogstaver.

- Biblioteket indlæses i hukommelsen, om nødvendigt.

- Modulet må ikke være et klasse-modul.

- Metoden kan være en Sub eller en Function

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 (virkefelt): En af de tilgængelige konstanter, som er opført ovenfor. Standardværdien er session.SCRIPTISSHARED.

script: Enten "library/module.py$method" eller "module.py$method" eller "myExtension.oxt|myScript|module.py$method" som en streng med forskel på store og små bogstaver.

- library (bibliotek): Mappestien til Python-modulet.

- myScript (mit script): Den mappe, der indeholder Python-modulet.

- module.py: Python-modulet.

- metode: Python-funktionen.

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

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 ▸ Eksportér som ▸ Eksportér 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.

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

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 forskel på store og små bogstaver

### 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 forskel på store og små bogstaver

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

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

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)

Denne metode er kun tilgængelig for Basic-scripts.

## UnoMethods

Returnerer en liste over metoder, der kan kaldes fra et UNO-objekt. Listen er et array med 0 som første indeks og kan være tomt.

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

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

Relaterede emner

Funktionen Matrix

Brug af Calc-funktioner i makroer

Kalde Python-scripts fra Basic

tjenesten ScriptForge.Basic

Tjenesten ScriptForge.FileSystem