Servizio ScriptForge.Session

Contenuto
Indice 🔎︎

# ScriptForge.Session service

Il servizio Session raggruppa diversi metodi di uso generale relativi a:

- l'ambiente d'installazione o di esecuzione

- l'introspezione di UNO

- l'invocazione di script o di programmi esterni

## Invocare il servizio

##### In Basic

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

##### In Python

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

## Costanti

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 | Valore | Dove si trova la libreria? | Applicabile
SCRIPTISEMBEDDED | "document" | nel documento | Basic + Python
SCRIPTISAPPLICATION | "application" | in qualsiasi libreria condivisa | Basic
SCRIPTISPERSONAL | "user" | nelle Macro personali | Python
SCRIPTISPERSOXT | "user:uno_packages" | in un'estensione installata per l'utente corrente | Python
SCRIPTISSHARED | "share" | nelle macro di LibreOffice | Python
SCRIPTISSHAROXT | "share:uno_packages" | in un'estensione installata per tutti gli utenti | Python
SCRIPTISOXT | "uno_packages" | in un'estensione della quale non si conoscono i parametri d'installazione | Python

Elenco dei metodi del servizio Session
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

Esegue lo script in Basic indicato in base al suo nome e posizione e ne recupera i risultati, se presenti.

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

### Sintassi:

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

### Parametri:

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.

### Esempio:

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

Esegue una funzione di Calc usando il suo nome in inglese e basandosi sugli argomenti indicati.
Se gli argomenti sono matrici, la funzione viene eseguita come una formula di matrice.

### Sintassi:

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

### Parametri:

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.

### Esempio:

##### 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)
        'Genera un errore.

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

Esegue lo script in Python in base alla sua posizione e al suo nome e ne recupera il risultato, se presente. Il risultato può essere un singolo valore o una matrice di valori.

Se lo script non viene trovato o non restituisce alcun valore, il valore restituito è Empty.

Lo Application Programming Interface (API) Scripting Framework (Infrastruttura per lo scripting) di LibreOffice supporta l'esecuzione interlinguistica di script tra Python e Basic o altri linguaggi di programmazione supportati per tale scopo. Gli argomenti possono essere passati tra le chiamate avanti e indietro, posto che essi rappresentino tipi di dati primitivi riconoscibili da entrambi i linguaggi, e presupponendo che lo Scripting Framework li converta in modo appropriato.

### Sintassi:

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

### Parametri:

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: il percorso della cartella che contiene il modulo Python.

- myScript: la cartella che contiene il modulo Python.

- module.py: il modulo Python.

- method: la funzione in Python.

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

### Esempio:

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

### Sintassi:

session.GetPDFExportOptions(): obj

### Esempio:

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

Questo metodo è disponibile solo per gli script Basic.

## HasUnoMethod

Restituisce True se un oggetto UNO contiene il metodo specificato. Restituisce False se il metodo non viene trovato o se un argomento non è valido.

### Sintassi:

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

### Parametri:

unoobject: The object to inspect.

methodname: the method as a case-sensitive string

### Esempio:

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

Restituisce True se un oggetto UNO contiene la proprietà specificata. Restituisce False se la proprietà non viene trovata o se un argomento non è valido.

### Sintassi:

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

### Parametri:

unoobject: The object to inspect.

propertyname: the property as a case-sensitive string

### Esempio:

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

Apre un Uniform Resource Locator (URL) nel browser predefinito.

### Sintassi:

session.OpenURLInBrowser(url: str)

### Parametri:

url: The URL to open.

### Esempio:

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

### Sintassi:

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

### Parametri:

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.

### Esempio:

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

Invia un messaggio - con degli allegati opzionali - a dei destinatari dal programma di posta elettronica dell'utente. Il messaggio può essere modificato dall'utente prima dell'invio o, in alternativa, essere inviato immediatamente.

### Sintassi:

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

### Parametri:

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.

### Esempio:

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

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

### Sintassi:

session.SetPDFExportOptions(pdfoptions: obj): bool

### Parametri:

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.

### Esempio:

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

Questo metodo è disponibile solo per gli script Basic.

## UnoMethods

Restituisce l'elenco dei metodi richiamabili da un oggetto UNO. L'elenco è una matrice di stringhe, con indice a partire da zero, che può essere vuota.

### Sintassi:

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

### Parametri:

unoobject: The object to inspect.

### Esempio:

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

Restituisce l'elenco delle proprietà di un oggetto UNO. L'elenco è una matrice di stringhe, con indice a partire da zero, che può essere vuota.

### Sintassi:

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

### Parametri:

unoobject: The object to inspect.

### Esempio:

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

Identifica il tipo di oggetto UNO in formato stringa.

### Sintassi:

session.UnoObjectType(unoobject: uno): str

### Parametri:

unoobject: The object to identify.

### Esempio:

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

Ottiene del contenuto web da un URI.

### Sintassi:

session.WebService(uri: str): str

### Parametri:

uri: URI address of the web service.

### Esempio:

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

Argomenti correlati

Funzione Array

Using Calc Functions in Macros

Richiamare script Python da Basic

Servizio ScriptForge.Basic

Servizio ScriptForge.FileSystem