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" as a case-sensitive string.
The library is loaded in memory if necessary.
The module must not be a class module.
The method may be a Sub or a Function.

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

Esempio:


      session.ExecuteBasicScript(, "XrayTool._Main.Xray", CreateUnoService("com.sun.star.util.TextSearch"))
      ' Xray returns no value
   

ExecuteCalcFunction

Execute a Calc function using its English name and based on the given arguments.
If the arguments are arrays, the function is executed as an array formula.

Sintassi:


      session.ExecuteCalcFunction(CalcFunction As String, arg0, ...) As Variant
   

Parametri:

CalcFunction: The English name of the function to execute.

arg0, ...: The arguments to provide to the called Calc function. Each argument must be either a string, a numeric value or an array of arrays combining those types.

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)
      ' Generates an error.
   

ExecutePythonScript

Execute the Python script given its location and name, fetch its result if any. Result can be a single value or an array of values.

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: One of the applicable session.CONSTANTS. Default = session.SCRIPTISSHARED.

Script: Either "library/module.py$method" or "module.py$method" or "myExtension.oxt|myScript|module.py$method" as a case-sensitive string.

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

Esempio:


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

HasUnoMethod

Returns True if an UNO object contains the given method. Returns False when the method is not found or when an argument is invalid.

Sintassi:


      session.HasUnoMethod(UnoObject As Object, MethodName As String) As Boolean
   

Parametri:

UnoObject: The object to inspect.

MethodName: the method as a case-sensitive string

Esempio:


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

HasUnoProperty

Returns True if a UNO object has the given property. Returns False when the property is not found or when an argument is invalid.

Sintassi:


      session.HasUnoProperty(UnoObject As Object, PropertyName As String) As Boolean
   

Parametri:

UnoObject: The object to inspect.

PropertyName: the property as a case-sensitive string

Esempio:


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

OpenURLInBrowser

Open a Uniform Resource Locator (URL) in the default browser.

Sintassi:


      session.OpenURLInBrowser(URL As String)
   

Parametri:

URL: The URL to open.

Esempio:


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

RunApplication

Executes an arbitrary system command and returns True if it was launched successfully.

Sintassi:


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

Parametri:

Command: The command to execute. This may be an executable file or a document which is registered with an application so that the system knows what application to launch for that document. The command must be expressed in the current SF_FileSystem.FileNaming notation.

Parameters: A list of space separated parameters as a single string. The method does not validate the given parameters, but only passes them to the specified command.

Esempio:


      session.RunApplication("Notepad.exe")
      session.RunApplication("C:\myFolder\myDocument.odt")
      session.RunApplication("kate", "/home/me/install.txt") ' GNU/Linux
   

SendMail

Send a message - with optional attachments - to recipients from the user's mail client. The message may be edited by the user before sending or, alternatively, be sent immediately.

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: An email address (the "To" recipient).

Cc: A comma-separated list of email addresses (the "carbon copy" recipients).

Bcc: A comma-separated list of email addresses (the "blind carbon copy" recipients).

Subject: the header of the message.

Body: The content of the message as an unformatted text.

FileNames: a comma-separated list of file names. Each file name must respect the SF_FileSystem.FileNaming notation.

EditMessage: When True (default), the message is edited before being sent.

Esempio:


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

UnoMethods

Returns a list of the methods callable from an UNO object. The list is a zero-based array of strings and may be empty.

Sintassi:


      session.UnoMethods(UnoObject As Object) As Variant
   

Parametri:

UnoObject: The object to inspect.

Esempio:


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

UnoProperties

Returns a list of the properties of an UNO object. The list is a zero-based array of strings and may be empty.

Sintassi:


      session.UnoProperties(UnoObject As Object) As Variant
   

Parametri:

UnoObject: The object to inspect.

Esempio:


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

UnoObjectType

Identify the type of a UNO object as a string.

Sintassi:


      session.UnoObjectType(UnoObject As Object) As String
   

Parametri:

UnoObject: The object to identify.

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.