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:
• 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
In Basic
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
Dim session As Variant
session = CreateScriptService("Session")
In Python
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.
| CONSTANT | Value | Where to find the library? | Applicable |
|---|---|---|---|
| SCRIPTISEMBEDDED | "document" | in the document | 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 Office 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 |
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.
Syntax:
session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any
Parameters:
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.
Example:
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.
In 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
In 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
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.
Syntax:
session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any
Parameters:
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.
Example:
In 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)
' Generates an error.
In 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
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.
The Office Application Programming Interface (API) Scripting Framework supports inter-language script execution between Python and Basic, or other supported programming languages for that matter. Arguments can be passed back and forth across calls, provided that they represent primitive data types that both languages recognise, and assuming that the Scripting Framework converts them appropriately.
Syntax:
session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any
Parameters:
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.
Example:
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.
In 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)
In Python
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 dialogue box, which can be accessed by choosing File - Export as - Export as PDF.
Export options set with the PDF Options dialogue box 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.
Syntax:
session.GetPDFExportOptions(): obj
Example:
In 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
' ...
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.
Syntax:
session.HasUnoMethod(unoobject: uno, methodname: str): bool
Parameters:
unoobject: The object to inspect.
methodname: the method as a case-sensitive string
Example:
In Basic
Dim a As Variant
a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox session.HasUnoMethod(a, "callFunction") ' True
In Python
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.
Syntax:
session.HasUnoProperty(unoobject: uno, propertyname: str): bool
Parameters:
unoobject: The object to inspect.
propertyname: the property as a case-sensitive string
Example:
In Basic
Dim svc As Variant
svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox session.HasUnoProperty(svc, "Wildcards")
In Python
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.
Syntax:
session.OpenURLInBrowser(url: str)
Parameters:
url: The URL to open.
Example:
' 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.
Syntax:
session.RunApplication(command: str, parameters: str): bool
Parameters:
command: The command to execute. This may be an executable file or a document which is registered with an application so that the system knows what application to launch for that document. The command must be expressed in the current SF-FileSystem.FileNaming notation.
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.
Example:
In Basic
session.RunApplication("Notepad.exe")
session.RunApplication("C:\myFolder\myDocument.odt")
session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux
In Python
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.
Syntax:
session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)
Parameters:
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.
Example:
In Basic
session.SendMail("someone@example.com" -
, Cc := "b@other.fr, c@other.be" -
, FileNames := "C:\myFile1.txt, C:\myFile2.txt")
In Python
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 dialogue box, which can be accessed by choosing File - Export as - Export as PDF.
Calling this method changes the actual values set in the PDF Options dialogue box, which are used by the ExportAsPDF method from the Document service.
This method returns True when successful.
Read the PDF Export wiki page to learn more about all available options.
Syntax:
session.SetPDFExportOptions(pdfoptions: obj): bool
Parameters:
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 dialogue box.
Example:
In Basic
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)
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.
Syntax:
session.UnoMethods(unoobject: uno): str[0..*]
Parameters:
unoobject: The object to inspect.
Example:
In 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
In Python
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.
Syntax:
session.UnoProperties(unoobject: uno): str[0..*]
Parameters:
unoobject: The object to inspect.
Example:
In Basic
Dim svc As Variant
svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
MsgBox SF-Array.Contains(session.UnoProperties(svc), "Wildcards") ' True
In 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
Identify the type of a UNO object as a string.
Syntax:
session.UnoObjectType(unoobject: uno): str
Parameters:
unoobject: The object to identify.
Example:
In 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"
In 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
Get some web content from a URI.
Syntax:
session.WebService(uri: str): str
Parameters:
uri: URI address of the web service.
Example:
In Basic
session.WebService("wiki.documentfoundation.org/api.php?" -
& "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")
In Python
session.WebService(("wiki.documentfoundation.org/api.php?"
"hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))
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.