Guida di LibreOffice 25.2
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
Prima di usare il servizio Session è necessario caricare o importare le librerie ScriptForge:
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim session As Variant
    session = CreateScriptService("Session")
  
    from scriptforge import CreateScriptService
    session = CreateScriptService("Session")
  Di seguito è riportato un elenco di costanti utili a semplificare la designazione della libreria contenente lo script in Basic o in Python da invocare. Usatele nel formato 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 dell'applicazione | 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 | 
             HasUnoProperty | |
I metodi Execute... del servizio Session si comportano come segue: 
Gli argomenti vengono passati in base al valore. Le modifiche apportate agli argomenti dalla funzione richiamata non aggiornano i loro valori nello script che l'ha invocata. 
Allo script che effettua la chiamata viene restituito un singolo valore o una matrice di valori.
Esegue lo script in BASIC indicato in base al suo nome e posizione e ne recupera i risultati, se presenti.
Se lo script non restituisce nulla, come nel caso delle procedure definite con Sub, il valore restituito è Empty.
session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any
scope: stringa che specifica dov'è memorizzato lo script. Può essere "document" (costante session.SCRIPTISEMBEDDED) o "application" (costante session.SCRIPTISAPPLICATION).
script: stringa che specifica lo script da richiamare nel formato "libreria.modulo.metodo" come stringa che distingue tra maiuscole e minuscole.
Se necessario, la libreria viene caricata in memoria.
Il modulo non deve appartenere a una classe.
Il metodo può essere una subroutine Sub o una funzione Function.
args: gli argomenti da passare allo script richiamato.
Prendete in considerazione la seguente funzione in Basic denominata DummyFunction, memorizzata in "Macro personali" nella libreria "Standard" all'interno di un modulo che si chiama "Module1".
La funzione semplicemente prende due valori interi v1 e v2 e restituisce la somma di tutti i valori partendo da v1 e arrivando a 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
  Gli esempi seguenti mostrano come chiamare la funzione DummyFunction dagli script in Basic e Python.
    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
  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.
session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any
calcfunction: il nome della funzione di Calc da richiamare, in inglese.
args: gli argomenti da passare alla funzione di Calc richiamata. Ogni argomento deve essere una stringa, un valore numerico o una matrice di matrici che combina quei tipi.
    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.
  
    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)
  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.
session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any
scope: una delle costanti applicabili elencate in precedenza. Il valore predefinito è session.SCRIPTISSHARED.
script: uno tra "libreria/modulo.py$metodo", "modulo.py$metodo" o "miaEstensione.oxt|mioScript|modulo.py$metodo" in formato stringa che distingue tra maiuscole e minuscole.
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: gli argomenti da passare allo script richiamato.
Prendete in considerazione la funzione in Python odd_integers definita di seguito, che crea un elenco di valori dispari interi compresi tra v1 e v2. Supponete che questa funzione sia memorizzata in un file denominato my_macros.py all'interno della vostra cartella degli script utente.
    def odd_integers(v1, v2):
        odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]
        return odd_list
  Per saperne di più sulla memorizzazione degli script in Python, consultare la pagina Organizzazione e posizione degli script Python di questa guida.
Gli esempi seguenti mostrano come invocare la funzione odd_integers dagli script in Basic e Python.
    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))
  Restituisce le impostazioni per l'esportazione di file in formato PDF definite nella finestra di dialogo , raggiungibile dal menu .
Le opzioni di esportazione impostate nella finestra di dialogo vengono mantenute per successivi utilizzi. Perciò GetPDFExportOptions restituisce le impostazioni correnti. In aggiunta, potete usare SetPDFExportOptions per modificare le opzioni correnti di esportazione in formato PDF.
Questo metodo restituisce un oggetto Dictionary in cui ogni chiave rappresenta un'opzione di esportazione e i valori corrispondenti sono le impostazioni correnti di esportazione in PDF.
Per conoscere tutte le opzioni disponibili, consultare la pagina wiki "PDF Export" (in inglese).
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
    ' ...
  Restituisce True se un oggetto UNO contiene il metodo specificato. Restituisce False se il metodo non viene trovato o se un argomento non è valido.
session.HasUnoMethod(unoobject: uno, methodname: str): bool
unoobject: l'oggetto da ispezionare.
methodname: il metodo in formato stringa, che distingue tra minuscole e maiuscole
    Dim a As Variant
    a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoMethod(a, "callFunction") ' True
  
    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoMethod(a, "callFunction")
    bas.MsgBox(result) # True
  Restituisce True se un oggetto UNO contiene la proprietà specificata. Restituisce False se la proprietà non viene trovata o se un argomento non è valido.
session.HasUnoProperty(unoobject: uno, propertyname: str): bool
unoobject: l'oggetto da ispezionare.
propertyname: la proprietà in formato stringa, che distingue tra maiuscole e minuscole
    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox session.HasUnoProperty(svc, "Wildcards")
  
    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    result = session.HasUnoProperty(a, "Wildcards")
    bas.MsgBox(result) # True
  Apre un Uniform Resource Locator (URL) nel browser predefinito.
session.OpenURLInBrowser(url: str)
url: l'URL da aprire.
    ' Basic
    session.OpenURLInBrowser("help.libreoffice.org/")
  
    # Python
    session.OpenURLInBrowser("help.libreoffice.org/")
  Esegue un comando di sistema arbitrario e restituisce True se è stato avviato correttamente.
session.RunApplication(command: str, parameters: str): bool
command: il comando da eseguire. Questo può essere un file eseguibile o un documento che è stato registrato associato a un'applicazione, in modo che il sistema sappia quale applicazione lanciare per quel documento. Questo metodo avvia allo stesso modo dei file .bat o degli script per la shell. Il comando deve essere espresso nella notazione SF_FileSystem.FileNaming correntemente in uso.
parameters: un elenco di parametri separati da spazi sotto forma di un'unica stringa. Il metodo non convalida i parametri indicati, ma semplicemente li passa al comando specificato.
    session.RunApplication("Notepad.exe")
    session.RunApplication("C:\\myFolder\\myDocument.odt")
    session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux
  
    session.RunApplication("Notepad.exe")
    session.RunApplication(r"C:\\myFolder\\myDocument.odt")
    session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux
  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.
session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)
recipient: un indirizzo di posta elettronica (il destinatario del campo "A").
cc: un elenco di indirizzi di posta elettronica separati da virgola (i destinatari del campo "copia conoscenza").
bcc: un elenco di indirizzi di posta elettronica separati da virgola (i destinatari del campo "copia conoscenza nascosta").
subject: l'oggetto del messaggio.
body: il contenuto del messaggio in formato testo non formattato.
filenames: un elenco di nomi di file separati da virgola. Ogni nome di file deve rispettare la notazione SF_FileSystem.FileNaming.
editmessage: se impostato su True (predefinito), il messaggio può essere modificato prima dell'invio.
    session.SendMail("someone@example.com" _
        , Cc := "b@other.fr, c@other.be" _
        , FileNames := "C:\myFile1.txt, C:\myFile2.txt")
  
    session.SendMail("someone@example.com",
                     cc="john@other.fr, mary@other.be"
                     filenames=r"C:\myFile1.txt, C:\myFile2.txt")
  Modifica le impostazioni di esportazione in formato PDF definite nella finestra di dialogo , raggiungibile dal menu .
L'invocazione di questo metodo modifica i valori effettivamente impostati nella finestra di dialogo , che sono usati dal metodo ExportAsPDF del servizio Document.
Questo metodo restituisce True, se eseguito correttamente.
Per conoscere tutte le opzioni disponibili, consultare la pagina wiki "PDF Export" (in inglese).
session.SetPDFExportOptions(pdfoptions: obj): bool
pdfoptions: oggetto Dictionary che definisce le opzioni di esportazione nel formato PDF da modificare. Ogni coppia chiave-valore rappresenta un'opzione di esportazione e il valore da impostare nella finestra di dialogo.
L'esempio seguente modifica la risoluzione massima delle immagini impostandola a 150 dpi ed esporta il documento corrente in un file PDF.
    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)
  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.
session.UnoMethods(unoobject: uno): str[0..*]
unoobject: l'oggetto da ispezionare.
    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
  
    bas = CreateScriptService("Basic")
    a = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    methods = session.UnoMethods(a)
    msg = "\n".join(methods)
    bas.MsgBox(msg)
  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.
session.UnoProperties(unoobject: uno): str[0..*]
unoobject: l'oggetto da ispezionare.
    Dim svc As Variant
    svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
    MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True
  
    bas = CreateScriptService("Basic")
    svc = bas.CreateUnoService("com.sun.star.sheet.FunctionAccess")
    properties = session.UnoProperties(a)
    b = "Wildcards" in properties
    bas.MsgBox(str(b)) # True
  Identifica il tipo di oggetto UNO in formato stringa.
session.UnoObjectType(unoobject: uno): str
unoobject: l'oggetto da identificare.
    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"
  
    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"
  Ottiene del contenuto web da un URI.
session.WebService(uri: str): str
uri: l'indirizzo URI del servizio web.
    session.WebService("wiki.documentfoundation.org/api.php?" _
        & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")
  
    session.WebService(("wiki.documentfoundation.org/api.php?" 
                       "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))