ScriptForge.Session service

The Session service gathers various general-purpose methods about:

A szolgáltatás igénybevétele

Before using the Session service the ScriptForge library needs to be loaded or imported:

note

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


A Basic nyelvben

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

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

Állandók

Below is a list of constants available to ease the designation of the library containing a Basic or Python script to invoke. Use them as session.CONSTANT.

CONSTANT

Érték

Where to find the library?

Alkalmazható

SCRIPTISEMBEDDED

"document"

a dokumentumban

Basic + Python

SCRIPTISAPPLICATION

"application"

in any shared library

Basic

SCRIPTISPERSONAL

"user"

in My Macros

Python

SCRIPTISPERSOXT

"user:uno_packages"

in an extension installed for the current user

Python

SCRIPTISSHARED

"share"

in Application Macros

Python

SCRIPTISSHAROXT

"share:uno_packages"

in an extension installed for all users

Python

SCRIPTISOXT

"uno_packages"

in an extension but the installation parameters are unknown

Python


List of Methods in the Session Service

ExecuteBasicScript
ExecuteCalcFunction
ExecutePythonScript
GetPDFExportOptions
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail
SetPDFExportOptions

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

A Session szolgáltatásban lévő Execute... metódusok a következőképpen viselkednek:
Az argumentumok átadása érték szerint történik. A hívott függvény által az argumentumokon végrehajtott változtatások nem frissítik azok értékét a hívó parancsfájlban.
A hívó parancsfájl egyetlen értéket vagy értékek tömbjét kapja vissza.


ExecuteBasicScript

Execute the BASIC script given its name and location, and fetch its result, if any.

If the script returns nothing, which is the case of procedures defined with Sub, the returned value is Empty.

Szintaxis:

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

Paraméterek:

scope: String specifying where the script is stored. It can be either "document" (constant session.SCRIPTISEMBEDDED) or "application" (constant session.SCRIPTISAPPLICATION).

script: String specifying the script to be called in the format "library.module.method" as a case-sensitive string.

args: The arguments to be passed to the called script.

Példa:

Consider the following Basic function named DummyFunction that is stored in "My Macros" in the "Standard" library inside a module named "Module1".

The function simply takes in two integer values v1 and v2 and return the sum of all values starting in v1 and ending in 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
  

The examples below show how to call DummyFunction from within Basic and Python scripts.

A Basic nyelvben

    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
  
A Python nyelvben

    session = CreateScriptService("Session")
    bas = CreateScriptService("Basic")
    b_script = 'Standard.Module1.DummyFunction'
    result = session.ExecuteBasicScript('application', b_script, 1, 10)
    bas.MsgBox(result) # 55
  

ExecuteCalcFunction

Execute a Calc function using its English name and based on the given arguments.
If the arguments are arrays, the function is executed as an array formula.

Szintaxis:

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

Paraméterek:

calcfunction: The name of the Calc function to be called, in English.

args: The arguments to be passed to the called Calc function. Each argument must be either a string, a numeric value or an array of arrays combining those types.

Példa:

A Basic nyelvben

    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)
    ' Generates an error.
  
A Python nyelvben

    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

Execute the Python script given its location and name, fetch its result if any. Result can be a single value or an array of values.

If the script is not found, or if it returns nothing, the returned value is Empty.

A LibreOffice Application Programming Interface (API) Scripting Framework támogatja a Python és a Basic, illetve más támogatott programozási nyelvek közötti nyelvközi parancsfájlfuttatást. Az argumentumok oda-vissza átadhatók a hívások között, feltéve, hogy olyan primitív adattípusokat képviselnek, amelyeket mindkét nyelv ismer, és feltéve, hogy a Scripting Framework megfelelően konvertálja őket.

Szintaxis:

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

Paraméterek:

scope: One of the applicable constants listed above. The default value is session.SCRIPTISSHARED.

script: Either "library/module.py$method" or "module.py$method" or "myExtension.oxt|myScript|module.py$method" as a case-sensitive string.

args: The arguments to be passed to the called script.

Példa:

Tekintsük az alábbiakban definiált odd_integers Python függvényt, amely egy listát hoz létre a v1 és v2 közötti páratlan egész számokkal. Tegyük fel, hogy ez a függvény a saját_makrók.py nevű fájlban van tárolva a felhasználói parancsfájlok mappában.


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

Read the help page Python Scripts Organization and Location to learn more about where Python scripts can be stored.


The following examples show how to call the function odd_integers from within Basic and Python scripts.

A Basic nyelvben

    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)
  
A Python nyelvben

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

GetPDFExportOptions

Returns the current PDF export settings defined in the PDF Options dialog, which can be accessed by choosing File - Export as - Export as PDF.

Export options set with the PDF Options dialog are kept for future use. Hence GetPDFExportOptions returns the settings currently defined. In addition, use SetPDFExportOptions to change current PDF export options.

This method returns a Dictionary object wherein each key represent export options and the corresponding values are the current PDF export settings.

tip

Read the PDF Export wiki page to learn more about all available options.


Szintaxis:

session.GetPDFExportOptions(): obj

Példa:

A Basic nyelvben

    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

This method is only available for Basic scripts.


HasUnoMethod

Returns True if an UNO object contains the given method. Returns False when the method is not found or when an argument is invalid.

Szintaxis:

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

Paraméterek:

unoobject: The object to inspect.

methodname: the method as a case-sensitive string

Példa:

A Basic nyelvben

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

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

HasUnoProperty

Returns True if a UNO object has the given property. Returns False when the property is not found or when an argument is invalid.

Szintaxis:

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

Paraméterek:

unoobject: The object to inspect.

propertyname: the property as a case-sensitive string

Példa:

A Basic nyelvben

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

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

OpenURLInBrowser

Open a Uniform Resource Locator (URL) in the default browser.

Szintaxis:

session.OpenURLInBrowser(url: str)

Paraméterek:

url: The URL to open.

Példa:


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

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

RunApplication

Executes an arbitrary system command and returns True if it was launched successfully.

Szintaxis:

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

Paraméterek:

command: A végrehajtandó parancs. Ez lehet egy futtatható fájl vagy egy dokumentum, amely egy alkalmazással van regisztrálva, hogy a rendszer tudja, milyen alkalmazást kell indítani az adott dokumentumhoz. A parancsot az aktuális SF_FileSystem.FileNaming jelöléssel kell kifejezni.

parameters: A list of space separated parameters as a single string. The method does not validate the given parameters, but only passes them to the specified command.

Példa:

A Basic nyelvben

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

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

SendMail

Send a message - with optional attachments - to recipients from the user's mail client. The message may be edited by the user before sending or, alternatively, be sent immediately.

Szintaxis:

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

Paraméterek:

recipient: An email address (the "To" recipient).

cc: A comma-separated list of email addresses (the "carbon copy" recipients).

bcc: A comma-separated list of email addresses (the "blind carbon copy" recipients).

subject: the header of the message.

body: The contents of the message as an unformatted text.

filenames: a comma-separated list of file names. Each file name must respect the SF_FileSystem.FileNaming notation.

editmessage: When True (default), the message is edited before being sent.

Példa:

A Basic nyelvben

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

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

SetPDFExportOptions

Modifies the PDF export settings defined in the PDF Options dialog, which can be accessed by choosing File - Export as - Export as PDF.

Calling this method changes the actual values set in the PDF Options dialog, which are used by the ExportAsPDF method from the Document service.

This method returns True when successful.

tip

Read the PDF Export wiki page to learn more about all available options.


Szintaxis:

session.SetPDFExportOptions(pdfoptions: obj): bool

Paraméterek:

pdfoptions: Dictionary object that defines the PDF export settings to be changed. Each key-value pair represents an export option and the value that will be set in the dialog.

Példa:

A Basic nyelvben

The following example changes the maximum image resolution to 150 dpi and exports the current document as a PDF file.


    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

This method is only available for Basic scripts.


UnoMethods

Returns a list of the methods callable from an UNO object. The list is a zero-based array of strings and may be empty.

Szintaxis:

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

Paraméterek:

unoobject: The object to inspect.

Példa:

A Basic nyelvben

    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
  
A Python nyelvben

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

UnoProperties

Returns a list of the properties of an UNO object. The list is a zero-based array of strings and may be empty.

Szintaxis:

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

Paraméterek:

unoobject: The object to inspect.

Példa:

A Basic nyelvben

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

    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

Identify the type of a UNO object as a string.

Szintaxis:

session.UnoObjectType(unoobject: uno): str

Paraméterek:

unoobject: The object to identify.

Példa:

A Basic nyelvben

    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"
  
A Python nyelvben

    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

Get some web content from a URI.

Szintaxis:

session.WebService(uri: str): str

Paraméterek:

uri: URI address of the web service.

Példa:

A Basic nyelvben

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

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.


Támogasson minket!