ScriptForge.Session service

The Session service gathers various general-purpose methods about:

• the installation or execution environment

• UNO introspection

• the invocation of external scripts or programs

Service invocation

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

• As macros en Basic requiren que se cargue a biblioteca ScriptForge empregando a instrución seguinte:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts en Python requiren unha importación do módulo scriptforge:
from scriptforge import CreateScriptService

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

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

Constants

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.

Execute... methods in Session service behave as follows:
Arguments are passed by value. Changes made by the called function to the arguments do not update their values in the calling script.
A single value or an array of values is returned to the calling script.

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.

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

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.

• The library is loaded in memory if necessary.

• The module must not be a class module.

• The method may be a Sub or a Function.

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

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.

    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
  

    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.

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

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.

    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.
  

    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.

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

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.

• library: The folder path to the Python module.

• myScript: The folder containing the Python module.

• module.py: The Python module.

• method: The Python function.

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

Consider the Python function odd_integers defined below that creates a list with odd integer values between v1 and v2. Suppose this function is stored in a file named my_macros.py in your user scripts folder.

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

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.

    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)
  

    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.

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

session.GetPDFExportOptions(): obj

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

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.

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

unoobject: The object to inspect.

methodname: the method as a case-sensitive string

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