Contenuto
Indice 🔎︎

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

## Invocare il servizio

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

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

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.

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

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

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.

Argomenti correlati

Funzione Array

Richiamare funzioni Calc

Richiamare script Python da Basic

Servizio ScriptForge.FileSystem