Sevizio ScriptForge.Session

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

Invocare il servizio

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

note

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


tip

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.

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.

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
  
tip

Per saperne di più sulla memorizzazione degli script in Python, consultate 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.

tip

Per conoscere tutte le opzioni disponibili, consultate 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
    ' ...
  
note

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

tip

Per conoscere tutte le opzioni disponibili, consultate 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)
  
note

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

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.


Sosteneteci!