Servizio ScriptForge.Session

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

Invocare il servizio


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

Questo servizio è pienamente supportato sia in Basic, sia in Python. Tutti gli esempi sono espressi nel linguaggio di programmazione Basic e possono essere facilmente convertiti in Python.


Costanti

Di seguito è riportato un elenco di costanti disponibili che facilitano la designazione della libreria che contiene 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
HasUnoMethod

HasUnoProperty
OpenURLInBrowser
RunApplication
SendMail

UnoMethods
UnoProperties
UnoObjectType
WebService


tip

I metodi del servizio Session si comportano nel modo seguente:
Gli argomenti sono passati per valore. Gli aggiornamenti eseguiti dalla funzioni chiamate non vengono inviati nuovamente allo script che lo ha chiamato.
A quest'ultimo 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 viene trovato o non restituisce alcun valore, il valore restituito è Empty.

Sintassi:


      session.ExecuteBasicScript([Scope As String], Script As String[, arg0 As Variant, ...]) As Variant
   

Parametri:

Scope: "document" o "application" o una delle costanti session.CONSTANTS applicabili.

Script: "library.module.method" in formato stringa che distingue tra maiuscole e minuscole.
Se necessario, la libreria viene caricata in memoria.
Il modulo non deve essere quello di una classe.
Il metodo può essere una Sub o una Function.

arg0, ...: gli argomenti da fornire allo script richiamato.

Esempio:


      session.ExecuteBasicScript(, "XrayTool._Main.Xray", CreateUnoService("com.sun.star.util.TextSearch"))
      'Xray non restituisce valori
   

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 As String, arg0, ...) As Variant
   

Parametri:

CalcFunction: il nome inglese della funzione da eseguire.

arg0, ...: gli argomenti da fornire alla funzione di Calc richiamata. Ogni argomento deve essere una stringa, un valore numerico o una matrice di matrici che combina questi tipi.

Esempio:


      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.
   

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] As String, Script As String[, arg0 As Variant, ...]) As Variant
   

Parametri:

Scope: una delle costanti session.CONSTANTS applicabili. Predefinito = session.SCRIPTISSHARED.

Script: uno tra "library/module.py$method", "module.py$method" o "myExtension.oxt|myScript|module.py$method" in formato stringa che distingue tra maiuscole e minuscole.

arg0, ...: gli argomenti da fornire allo script richiamato.

Esempio:


      session.ExecutePythonScript(session.SCRIPTISSHARED, "Capitalise.py$getNewString", "Abc") ' "abc"
   

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 As Object, MethodName As String) As Boolean
   

Parametri:

UnoObject: l'oggetto da ispezionare.

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

Esempio:


      Dim a As Variant
      a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
      MsgBox session.HasUnoMethod(a, "callFunction")
   

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 As Object, PropertyName As String) As Boolean
   

Parametri:

UnoObject: l'oggetto da ispezionare.

PropertyName: la proprietĂ  in formato stringa che distingue tra maiuscole e minuscole

Esempio:


      Dim svc As Variant
      svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
      MsgBox session.HasUnoProperty(svc, "Wildcards")
   

OpenURLInBrowser

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

Sintassi:


      session.OpenURLInBrowser(URL As String)
   

Parametri:

URL: l'URL da aprire.

Esempio:


      session.OpenURLInBrowser("https://docs.python.org/3/library/webbrowser.html")
   

RunApplication

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

Sintassi:


      session.RunApplication(Command As String, Parameters As String) As Boolean
   

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:


      session.RunApplication("Notepad.exe")
      session.RunApplication("C:\myFolder\myDocument.odt")
      session.RunApplication("kate", "/home/me/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 As String, [Cc As String], [Bcc As String], [Subject As String], [Body As String], [FileNames As String], [EditMessage As Boolean])
   

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:


      session.SendMail("a@example.com" _
          , Cc := "b@other.fr, c@other.be" _
          , FileNames := "C:\myFile1.txt, C:\myFile2.txt" _
          )
   

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 As Object) As Variant
   

Parametri:

UnoObject: l'oggetto da ispezionare.

Esempio:


      Dim a As Variant
      a = CreateUnoService("com.sun.star.sheet.FunctionAccess")
      MsgBox SF_Array.Contains(session.UnoMethods(a), "callFunction")
   

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 As Object) As Variant
   

Parametri:

UnoObject: l'oggetto da ispezionare.

Esempio:


      Dim svc As Variant
      svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")
      MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards")
   

UnoObjectType

Identifica il tipo di oggetto UNO in formato stringa.

Sintassi:


      session.UnoObjectType(UnoObject As Object) As String
   

Parametri:

UnoObject: l'oggetto da identificare.

Esempio:


      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"
   

WebService

Ottiene del contenuto web da un URI.

Sintassi:


      session.WebService(URI As String) As String
   

Parametri:

URI: il testo URI del servizio web.

Esempio:


      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.


Sosteneteci!