Servizio ScriptForge.Services

La libreria ScriptForge è costruita basandosi su una raccolta estensibile di cosiddetti "Servizi".
Questa raccolta viene implementata con categorie di librerie in Basic o di moduli in Python:

  1. la libreria ScriptForge standard fornita con LibreOffice

  2. una serie di librerie "associate", fornite anch'esse con LibreOffice

  3. qualsiasi estensione di LibreOffice di utenti o collaboratori che desiderano inglobarla nella stessa infrastruttura

Un service è una raccolta di proprietà e metodi che implementa il servizio.

tip

Per l'autore di uno script utente, un servizio può essere o un modulo all'interno di una libreria, o una istanza del modulo di una classe.


Un gestore degli eventi (event manager) è uno script contenuto in una libreria che lega un evento che attiva una macro - di solito definito nel menu Strumenti - Personalizza - all'istanza del servizio interessata.

tip

Ad esempio, se più documenti durante il loro caricamento attivano la stessa macro, potrebbe essere utile sapere quale documento ha attivato tale macro. Qui è dove il gestore degli eventi entra in gioco.


I metodi seguenti costituiscono il nocciolo del framework ScriptForge:

tip

Per convenzione i servizi String, Array e Exception possono essere invocati direttamente come SF_String, SF_Array e SF_Exception, rispettivamente.


Elenco dei metodi del servizio Services

CreateScriptService

RegisterScriptServices
RegisterService

RegisterEventManager


CreateScriptService

Ottiene l'accesso a uno dei servizi della libreria a vantaggio di uno script utente.
Il valore restituito è un oggetto Basic o Nothing se si verifica un errore.

Un servizio può essere inteso come uno fra:

Sintassi:


       CreateScriptService(Service As String, [arg0, ...] As Variant) As Variant
      

Parametri:

Service: il nome del servizio identificato come "library.service".
La libreria è una libreria di Basic che deve esistere nel GlobalScope. Il valore predefinito è "ScriptForge".
Il servizio è uno di quelli registrati dalla libreria tramite il metodo RegisterScriptServices().

arg0, ...: un elenco di argomenti richiesti dal servizio invocato.
Se il primo argomento si riferisce a un gestore degli eventi, allora arg0 è obbligatorio e deve essere un oggetto UNO che rappresenta l'evento fornito come argomento alla macro dell'utente.

Esempio:


        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        'Da eseguire una volta
        Dim svc As Object
        Set svc = CreateScriptService("Array")
        'Fa riferimento al servizio "ScriptForge.Array" o SF_Array
        Set svc = CreateScriptService("ScriptForge.Dictionary")
        'Restituisce una nuova istanza alla classe di un nuovo dizionario vuoto; "ScriptForge." è opzionale
        Set svc = CreateScriptService("SFDocuments.Calc")
        'Fa riferimento al servizio Calc, implementato nella libreria associata SFDocuments
        Set svc = CreateScriptService("Timer", True)
        'Restituisce un'istanza della classe Timer che si avvia immediatamente
        Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)
        'Fa riferimento al servizio DocumentEvent implementato nella libreria associata SFDocuments
        'Restituisce un'istanza della classe Document che ha innescato l'evento
     

RegisterScriptServices

Eseguendo una serie di invocazioni di RegisterService() e RegisterEventManager(), il metodo RegisterScriptServices() incorpora una libreria nel framework ScriptForge.
Ogni libreria appartenente al framework deve implementare la propria versione di questo metodo.

warning

Il metodo deve essere memorizzato in un modulo standard di Basic al contrario di un modulo di classe.


Un servizio può essere:


          GlobalScope.LibraryName.ModuleName ' Oggetto
          "LibraryName.ModuleName.FunctionName" ' Stringa
   

Esempio:


      Public Sub RegisterScriptServices()
      ' To be stored in library = myLibrary
          With GlobalScope.ScriptForge.SF_Services
              .RegisterService("myService1", GlobalScope.myLibrary.myModule)
              'Fa riferimento a un modulo standard di Basic che implementa il servizio come insieme di metodi
              .RegisterService("myService2", "myLibrary.someModule.someFunction")
              'La funzione deve restituire un'istanza di una classe di oggetti di Basic che implementa il servizio
              ' ...
          End With
      End Sub
   

Quando lo script dell'utente contiene un'istruzione come:

Set myServ = CreateScriptService("myLibrary.myService1")


ScriptForge esegue queste operazioni:

  1. carica la libreria myLibrary, se necessario

  2. invoca il metodo RegisterScriptServices per caricare in memoria l'elenco dei servizi di myLibrary

  3. inizializza la variabile myServ con il servizio indicato

RegisterService

Il metodo restituisce True se la coppia nome-valore indicata come argomento può essere registrata correttamente.

Sintassi:


      GlobalScope.ScriptForge.SF_Services.RegisterService(ServiceName As String, ServiceReference As Variant) As Boolean
   

Parametri:

ServiceName: il nome del servizio in formato stringa che non distingue tra minuscole e maiuscole. Il nome deve essere univoco.

ServiceReference - il riferimento a un servizio può essere:


          GlobalScope.LibraryName.ModuleName ' Oggetto
          "LibraryName.ModuleName.FunctionName" ' Stringa
   

Esempio:


          With GlobalScope.ScriptForge.SF_Services
              .RegisterService("myService1", GlobalScope.myLibrary.myModule)
              'Fa riferimento a un modulo standard di Basic che implementa il servizio come insieme di metodi
              .RegisterService("myService2", "myLibrary.someModule.someFunction")
              'La funzione deve restituire un'istanza di una classe di oggetti di Basic che implementa il servizio
              ' ...
          End With
   

RegisterEventManager

Il metodo restituisce True se la coppia nome-valore indicata come argomento può essere registrata correttamente.

Sintassi:


      GlobalScope.ScriptForge.SF_Services.RegisterEventManager(ServiceName As String, ServiceReference As String) As Boolean
   

Parametri:

ServiceName: il nome del servizio in formato stringa che non distingue tra minuscole e maiuscole. Il nome deve essere univoco.

ServiceReference: una stringa che designa la funzione da eseguire per ottenere un'istanza del servizio. Di fatto è la funzione che contiene la parola chiave New di un'istruzione Set a creare l'istanza:

    "LibraryName.ModuleName.FunctionName" ' String

Esempio:


          With GlobalScope.ScriptForge.SF_Services
              .RegisterEventManager("myEventMgr", "myLibrary.someModule.someFunction")
              'La funzione dovrebbe restituire un'istanza dell'oggetto della classe di Basic che implementa il servizio
              ' ...
          End With
  
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!