Contenuto

# Sevizio ScriptForge.Session

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

## Invocazione del servizio

Prima di usare il servizio Session è necessario caricare o importare le librerie ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
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")

## Costanti

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 ExecuteCalcFunction ExecutePythonScript GetPDFExportOptions HasUnoMethod | HasUnoProperty OpenURLInBrowser RunApplication SendMail SetPDFExportOptions | UnoMethods UnoProperties UnoObjectType WebService

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.

## ExecuteBasicScript

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.

### Sintassi:

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

### Parametri:

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.

### Esempio:

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.

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

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

### Esempio:

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.

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

Restituisce le impostazioni per l'esportazione di file in formato PDF definite nella finestra di dialogo Opzioni PDF, raggiungibile dal menu File - Esporta come - Esporta nel formato PDF.

Le opzioni di esportazione impostate nella finestra di dialogo Opzioni PDF 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).

### 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: l'oggetto da ispezionare.

methodname: il metodo in formato stringa, che distingue tra minuscole e maiuscole

### 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: l'oggetto da ispezionare.

propertyname: la proprietà in formato stringa, che distingue tra maiuscole e minuscole

### 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: l'URL da aprire.

### Esempio:

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

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

## RunApplication

Esegue un comando di sistema arbitrario e restituisce True se è stato avviato correttamente.

### Sintassi:

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

### Parametri:

command: il comando da eseguire. Può essere un file eseguibile o un documento associato a un'applicazione, in modo che il sistema sappia quale applicazione avviare per aprire quel documento. Il comando deve essere espresso nella notazione SF_FileSystem.FileNaming corrente.

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.

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

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

Modifica le impostazioni di esportazione in formato PDF definite nella finestra di dialogo Opzioni PDF, raggiungibile dal menu File - Esporta come - Esporta nel formato PDF.

L'invocazione di questo metodo modifica i valori effettivamente impostati nella finestra di dialogo Opzioni PDF, 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).

### Sintassi:

session.SetPDFExportOptions(pdfoptions: obj): bool

### Parametri:

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.

### Esempio:

##### In Basic

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)

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: l'oggetto da ispezionare.

### 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: l'oggetto da ispezionare.

### 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: l'oggetto da identificare.

### 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: l'indirizzo URI del servizio web.

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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Argomenti correlati

Funzione Array

Utilizzo delle funzioni di Calc nelle macro

Richiamare script Python da Basic

Servizio ScriptForge.Basic

Servizio ScriptForge.FileSystem