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.

Funzione Array

Utilizzo delle funzioni di Calc nelle macro

Richiamare script Python da Basic

Servizio ScriptForge.Basic

Servizio ScriptForge.FileSystem